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1.1. Overview 




Introduction 



This document describes the Pixrect graphics library, a set of routines that mani- 
pulate rectangular arrays of pixel values, on screen or in memory. These routines, 
called RasterOps, are common to all Sun workstations. With these routines, 
application programs can manipulate the bit-mapped display on any Sun Works- 
tation. 

From a software perspective, the Pixrect graphics library is a low-level graphics 
package, sitting on top of the display device drivers. For most applications, the 
higher-level abstractions available in SunView and the Sun graphic standards 
libraries are more appropriate. For more information on these other packages, 
see the preface of this manual for references. 

The Pixrect library is intended only for accessing and manipulating two- 
dimensional, rectangular regions of a display device in a device-independent 
fashion. 

Windows 

The Pixrect library does not support overlapping windows. These can be 
implemented with memory pixrects by the application, but the SunView 
package already offers a sophisticated, easy-to-use programming interface 
for this purpose. 

Input Devices 

The Pixrect library does not have input functions. An application can use 
the input functions available in SunView, or make system calls directly to the 
raw input devices (see mouse(4) and kbd(4)). 

This manual is divided into chapters that describe the major features of the Pix- 
rect library. This chapter provides an introduction to the Pixrect library, defining 
important terms and concepts, and describing the resources available to the pro- 
grammer. Chapter 2 explains how to write Pixrect programs that can run on all 
Sun systems. Chapter 3 covers the operations for opening and manipulating pix- 
rects. Chapter 4 describes the text facilities in the Pixrect library. Chapter 5 
discusses memory pixrects, rectangular regions of virtual memory that are mani- 
pulated as pixrects. Chapter 6 explains the file I/O functions in the Pixrect 
library. These functions can be used to store and retrieve pixrects from disk files. 
Appendix A is a implementation guide for writing pixrect device drivers. 
Appendix B is a list of the functions and macros in the Pixrect library. Appendix 
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C is a list of types and structures in the Pixrect library. Appendix D describes 
the curve facilities in Pixrect . 



1.2. Important Concepts This section describes some of the important concepts behind the Pixrect library. 

It is not intended to be complete but rather to explain some features of the Pixrect 
library that make it unique among graphics packages. 



o x 




Screen Coordinates 

The screen coordinate system is two dimensional; the origin is in the upper 
left comer, with x and y increasing to the right and down. The coordinates 
describing pixel locations in a pixrect are integers ranging from 0 to the 
pixrect’s width (for x) or height (for y) minus 1 . The maximum value for x 
and y is 32767. 

Pixels 

A pixel is the smallest individual picture element that can be displayed on 
the screen. A pixel has an address (corresponding to an x and y coordinate) 
used to specify it, and a value, which controls the color displayed. The pixel 
address can be absolute (its screen coordinate) or relative to some rectangu- 
lar sub-region of the screen. A pixel has a depth (the number of bits it con- 
tains) which determines the range of colors it can display. A single bit pixel 
can be only black or white, and are used in monochrome displays. Pixels 
with more bits can display grayscale values or color. The most common 
pixel depths are one, eight, sixteen, or twenty-four bits per pixel. 

Bitmaps 

A bitmap is a rectangular region of screen space. Each pixel on the screen 
corresponds to some number of bits in the screen memory. The value of 
these bits determines the color of the corresponding pixel. These groups are 
arranged in an array that can be accessed using the x and y coordinates of the 
corresponding pixel. A pixrect bitmap can be up to 32767 pixels wide, and 
up to 32767 pixels high. 

The word “bitmap” can describe the the type of display, indicating it uses 
raster (rather than vector) display technology, or more commonly, to the 
images stored in bitmap format. Examples of the second type of bitmap 
include the screen image, window images, the cursor, or icons. 

RasterOps 

RasterOps are the legal operations available for modifying pixrects. A 
rasterop is an operation which takes two bitmaps as arguments: a source bit- 
map, and the current state of the destination bitmap. The RasterOp then per- 
forms a boolean operation using these arguments, pixel by pixel, writing the 
final result to the destination bitmap. The source bitmap may be pattern, or 
defined as a region of some constant value. 

The pr_stencil ( ) function is the only RasterOp that breaks this rule. 
Along with the source and destination bitmaps, this function takes an addi- 
tional argument, a texture bitmap, and combines the three in a boolean 
operation. See Chapter 3 for a more detailed explanation of the RasterOp 
functions available in the Pixrect graphics library. 
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Figure 1-1 RasterOp Function 




Pixrects 

A pixrect is the graphics analogy to an instance of a class used in object- 
oriented programming languages. It consists of bitmap data and the opera- 
tions that can be performed on that data. The implementation of the opera- 
tions and the data itself is hidden from the programmer (the only exception 
is memory pixrects, whose bitmap data can be directly manipulated. See 
Chapter 5 for details.) The pixrect is manipulated by using one of the func- 
tions in the pixrect library valid for that pixrect (analogous to sending it a 
message in object-oriented Programming.) 

A pixrect object can reside on a variety of devices; including different types of 
graphics displays, memory, and printers. Since the available operations are the 
same regardless of the device the pixrect resides in, the programmer can ignore 
device particularities while writing the application. 

1.3. Using Pixrects The general procedure for drawing pictures using pixrects takes three steps: 

1 . Open a pixrect object. 

2. Draw a picture into the pixrect, using the set of valid operations: 

pr_put ( ) 
pr_vector ( ) 
pr_r op ( ) 
etc. 

3. Close the pixrect. 

Primary Pixrect If the pixrect resides on a display device, the result of each drawing operation 

becomes visible immediately. Opening a display pixrect will not erase the previ- 
ous contents of the display. Closing the pixrect also has no effect on the contents 
of the display. 
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Secondary Pixrect 



Memory Pixrect 



Basic Example 



Compiling 



A secondary pixrect is a proper subset of its parent pixrect. The results of draw- 
ing operations to a secondary pixrect are displayed immediately, if the parent’s 
pixrect is visible. A secondary pixrect can simplify programming, by allowing 
the programmer to isolate a section of a larger pixrect, sending drawing com- 
mands relative to that pixrect, rather than to its parent. Pixrects can be nested to 
any depth. 

A memory pixrect allocates a section of memory in the woricstation. Unlike a 
primary or secondary pixrect, a memory pixrect does clear its bitmap to zeros 
when opened. Operations done on memory pixrects don’t show on the screen. 

An image in a memory pixrect can be copied to a display pixrect, allowing a sim- 
ple form of double buffering. A memory pixrect can also be used a buffer or 
scratch pad, storing bitmaps for later use, or to save the results of previous opera- 
tions. 

The following example draws a diagonal line near the upper comer of the 
woricstation’ s default display. 

Figure 1-2 Basic Example Program 

— 
♦include <pixrect/pixrect_hs .h> 

main ( ) 

1 

Pixrect *screen; 

screen = pr_open ("/dev/fb") ; 

pr_vector (screen, 10, 20, 70, 80, PIX_SET, 1); 
pr_close (screen) ; 

} 

s J 



The header file <pixrect/pixrect_hs . h> #includes all of the header 
files necessary for working with the functions, macros and data structures in the 
Pixrect library. 



The example program can be compiled as follows: 



f 

example^ cc line . c -o line -lpixrect 




v ' 





This command line compiles the program in line . c. The -lpixrect option 
causes the C compiler to link the Pixrect library to the application program and 
create an executable file named line. 



The sample program can be executed by the SunOS C-shell: 




A diagonal line will appear in the upper left hand comer of the screen. 
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Pixrect lint Library Pixrect provides a 1 int (1) library, which allows 1 in t to check your program 

beyond the capabilities of the C compiler. Using the -lpixrect flag provides 
lint with pixrect-specific information that prevents bogus error messages. You 
could use lint to check a program called box . c with command like this: 




Note that most of the error messages generated by lint are warnings, and may 
not necessarily have any effect on the operation of the program. For a detailed 
explanation of lint, see the discussion on lint in the C Programmer’ s Guide 
manual. 

1.4. Pixrect Data All of the important Pixrect data structures are stored in the header files shown in 

Structures the table below. They can be found in the /usr/include/pixrect direc- 

tory. Use these files to look up the exact definition of a function or macro you’re 
not sure about. 

Table 1-1 Pixrect Header Files 



pixrect_hs .h 


#includes all pixrect files 


pixrect .h 


most pixrect definitions 


memvar . h 


memory pixrects 


pixfont .h 


text operations 


traprop.h 


traprop definitions 


pr_line .h 


defines wide and textured vectors 


pr_planegroups .h 


frame buffers 


pr util 


internal definitions 
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Portability Considerations 



This chapter addresses Pixrect portability between different Sun architectures. 
Since Pixrects is a low-level graphics library, it is not completely device 
independent. Currently, the only Sun architecture that brings up porting issues is 
Sun386i, the first Sun system to use the Intel 80386 processor. The pixrect 
software has been designed to minimize porting difficulties; nevertheless, there 
are some portability factors to take into consideration. 

The sections below describe the portability problems caused by the Sun386i sys- 
tem, and their solutions. 

2.1. Byte Ordering The 80386, 68020, and SPARC are 32-bit processors. This means that all data read 

or written by these processors pass through 32-bit wide registers. The order in 
which the data — the bytes and bits — are arranged in the 80386’ s registers 
differs from the 680X0 and SPARC families. These differences are illustrated in 
the figure below: 

Figure 2-1 Byte and Bit Ordering in the 80386, 680X0 and SPARC 

80386 

31 30 29 28 27 26 25 24 23 22 21 20 19 1817 16 15 14 13 1211 10 09 08 07 06 05 04 03 02 01 00 



Byte n+3 


Byte n+2 


Byte n+1 


Byte n 


Word n+1 


Word n 


Doubleword n 



680X0 and SPARC 



31 3029 28 27 26 25 24 23 222120191817 16 15 14 13 1211 100908 0706 05 0403 020100 



Byte n Byte n+1 


Byte n+2 


Byte n+3 


Word n 


Word n+1 


Longword n 



Byte Swapping and Bit The Sun386i is based on the 80386 processor, which handles byte ordering dif- 

Flipping ferently than 680X0 and SPARC processors. This affects the Sun386i’s interpreta- 

tion of graphics files — font files, icon files, cursor files, and screendumps — 
generated by the other two architectures. Typically, frame buffers are accessed 
as if they were word (i.e., 16-bit integer) devices, or as an array of words. 

Because the byte ordering of words is different on the two architectures. 
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transferring a graphics file from one to the other will usually result in a garbled 
picture. 

On 680X0 monochrome frame buffer, the bits are shifted out of the word starting 
at the most significant bit, bit 15. The upper left-most pixel on the screen is bit 
15, word 0 of the frame buffer memory. The next pixel, scanning from left to 
right as you view the screen, is bit 14. The pixel to the right of the first 16 pixels 
displayed comes from word 1 , bit 15. When interpreted as integers, the most 
significant and least significant bytes are: 



680X0 





MSB 


LSB 


word 0 


15 1413 1211 10 9 8 


76543210 


word 1 


15 14 13 121110 9 8 


76543210 


. . . 






word n 1 


15 1413 1211 10 9 8 


76543210 



For example, the integer (word) value 0x37 0D in word 0 would show up on the 
680X0 and SPARC monochrome frame buffer as the pixel sequence: 

. 

On the 80386 monochrome frame buffer, the bits are shifted out of the word from 
the least significant bit, bit 0, to the most, bit 15: 

80386 





LSB 


MSB 


word 0 


01234567 


8 9 1011 12 13 14 15 


word 1 


01234567 


8 9 1011 12 13 14 15 








word n 


01234567 


8 9 10 11 12 13 14 15 



For example, the integer (word) value 0x370D in word 0 would show up on the 
screen with the 80386 frame buffer as the pixel sequence: 

The bytes are backward and the bits are in the opposite order. Because graphics 
files are usually generated as an array of words, the bytes are backward for a typi- 
cal 80386 frame buffer when handling files generated by 680X0 and SPARC 
machines. Eight-bit color frame buffers represent each pixel as a byte of data, so 
the bit order is already correct; conversion only requires byte swapping. 

For monochrome frame buffers, each pixel is represented by a single bit; scan- 
ning from right to left presents a bit flip and byte swap problem. The right-most 
(low-order) bit of a bit field now represents the left-most pixel on the screen. 

Because of the large number of existing files using it, the 680X0/SPARC format is 
the standard format for describing graphics images on all Sun systems. This 
eliminates the need for two sets of files in a mixed-architecture network. Conse- 
quently, if you are porting programs to the Sun386i from other Sun systems — 
programs that access the frame buffer through SunView and Pixrect — byte and 
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bit ordering is handled automatically at run time. The 680X0/SPARC format 
images are converted to 80386 format. 

2.2. Flipping Pixrects Sun386i systems convert 680X0/SPARC format images into 80386 format just 

before they are used. The procedure that converts them is a new Pixrect routine, 
pr_f lip ( ) , found only in the Sun386i version of Pixrect. 



The internal data of a pixrect is referenced by its pr data field. 




If its a memory pixrect, the structure referenced by pr_dat a is: 




There are two new flag bits in the md_f lags word, to control the operation of 
pr_f lip ( ) . The flags MP_REVERSEVIDEO, MP_DISPLAY, and 
MP_P LANEMASK are now followed by MP_I38 6 and MP_STATIC. If true, 
MP_I38 6 indicates that the pixrect in question is already in Sun386i ( 80386) 
display format, i.e., it has already been modified by pr_f lip ( ) . If 
MP_STATIC is true, the pixrect in question is a static pixrect. (In practice, this 
flag is sometimes set for other purposes as well.) 

The pr_f lip ( ) Routine Thepr_flip() routine operates on individual pixrects. It takes one argument, 

a pointer to a pixrect structure, and returns void. When called, it first checks to 
see if the pixrect has already been flipped ( MP_1 386 == TRUE). If not, it flips 
the image area, 16 bits at a time. First the bit order is reversed, then the bytes are 
swapped. It will not flip a display pixrect or a secondary pixrect unless it is static 
( MP_STATIC == TRUE). 

When a pixrect is modified by a pr_f lip ( ) call, the changes are limited to the 
pixrect’s image area and the state of the two new mdf lags. The size of the 
pixrect structures remains unaltered. The new md_f lags are ignored by pro- 
grams running under 680X0 or SPARC. 

Pixrects are flipped as they are manipulated by any of the Pixrect routines listed 
below. As an application runs, the rate of pixrect flipping usually declines, since 
most applications develop a "working set” of active pixrects. Pixrects that are 
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not used are not flipped. 

The routines listed contain checkpoints, where pixrects used in the routines’ 
arguments are examined and flipped (if necessary) by pr_f lip ( ) : 

Table 2-1 Routines that call pr_flip() 

mem_rop ( ) 
mem_create () 
pr_region ( ) 
pr_vector ( ) 
pr_dump_init ( ) 
pf_open ( ) 
pf_open_j?rivate ( ) 
pr_stencil ( ) 
pr_batchrop ( ) 
pr_replrop ( ) 
pr_get ( ) 
pr_put ( ) 
pr_load( ) 
pr_dump ( ) 

icon_display ( ) 

DEFINE ICON FROM IMAGE 



NOTE Icons are either static or created with icon_load ( ) . Static icons can be 

created with DEFINE_ICON_FROM_IMAGE Both of these Sunview features are 
described in the SunView 1 Programmer’ s Guide. 

Fonts are converted by the pf_open ( ) or pf_open_private ( ) routines. 
No other conversions are allowed. The libraries work only with the existing 

standard font files. 



Guidelines for Sun386i 
Systems 



1 . Check code that draws manually into a pixrect. It may not work properly on 
a Sun386i without modification. The modification required depends on the 
particulars of the drawing operation. 

2. Manual operations (not involving libpixrect routines) should be per- 
formed on a pixrect before converting it to 80386 format. 

3. mem_creat e ( ) creates an 80386-format pixrect on Sun386i machines. 

4. mem_point does not set the MP I 386 flag. The pixrect is still marked 
not flipped. 

5. To create an icon, use mem_point ( ) to make a pixrect connected to an 
existing static image or an image that you have created dynamically. 

6. Use DEFlNE_ICON_FROM_IMAGE (SunView) to create static icons. All 
static icons are initially created in 680X0/SPARC format. They are converted 
to 80386 format when they are involved in a raster operation. 
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Pixrect Operations 



Pixrect objects contain procedures to perform the following operations: 

o create or destroy a pixrect (pr_open ( ) , pr_region ( ) and 
pr_destroy ( ) ). 

□ read and write the values of single pixels within a pixrect (pr_get and 
pr_put ( ) ). 

□ use RasterOp functions to simultaneously affect multiple pixels within a pix- 
rect: 

pr_rop write from a source pixrect to a destination pixrect, 

pr_stencil write from a source pixrect to a destination pixrect through 
a mask pixrect, 

pr_replrop replicate a constant source pixrect pattern throughout a des- 
tination pixrect, 

pr_batchrop 

write a batch of source pixrects to a sequence of locations 
within a single destination pixrect, 

pr_vector , pr_line 

draw a straight line in a pixrect, 

pr_polygon_2 

draw a polygon in a pixrect. 

□ draw text (described in chapter 4, Text Facilities for Pixrects). 

□ read write the display’s colormap (pr_get colormap ( ) , 
pr_putcolormap ( ) ) 

□ select particular bit-planes in a color pixrect’ s bitmap for manipulation 
(pr_get attributes ( ) , pr_putattributes ( ) ) 

□ control hardware double-buffering ( pr_dbl get ( ) and 
pr_dbl_set ( ) ). 

From an object-oriented viewpoint, all pixrects contain both data and procedures 
to manipulate its data. This allows pixrects to be device-independent; the pixrect 
uses the function appropriate for its environment when asked to perform an 
operation. 
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From the programmers point of view, pixrects are manipulated using procedure 
calls embedded in application program. Internally, the pixrect procedures that 
act the same for all pixrects are implemented by a single procedure for efficiency. 
The device-dependent calls are macros that access the appropriate procedure 
within the pixrect object. This is roughly equivalent to passing the pixrect object 
a message, which causes the pixrect to invoke the appropriate method (pro- 
cedure). 

Each pixrect object includes an internal pointer to a pixrectops structure, that 
holds the addresses of the particular device-dependent procedures appropriate to 
that pixrect. Clients may access these procedures in a device-independent 
fashion, by calling the procedure through the pixrectops structure, rather 
than executing the procedure directly. To simplify this indirection, the Pixrect 
library provides a set of macros which look like simple procedure calls to generic 
operations, which expand to invocations of the corresponding procedure in the 
pixrectops structure. 

In this manual, the description of each operation will specify whether it is a true 
procedure or a macro, since some of the arguments to macros are expanded mul- 
tiple times, and could cause errors if the arguments contain expressions with side 
effects. (In faci, there are two sets of parallel macros, which differ only in how 
their arguments use the geometry data structures.) 



3.1. The pixrectops 

Structure 




The pixrectops structure is a collection of pointers to the device-dependent 
procedures for a particular device. All other operations are implemented by 
device-independent procedures. From the object oriented view, this structure 
provides the procedural interface to the pixrect object, translating messages to 
methods. This structure is designed to allow expansion; additional functions 
may be added in future releases. 
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3.2. Callings Pixrect 
Procedures 



Argument Conventions 



Table 3-1 



Pixrect Errors 



3.3. The Op Argument 



Figure 3-1 



A Pixrect procedure normally expects a number of arguments. These arguments 
can include: a pointer to the pixrect being manipulated, the dimensions and offset 
of a subregion within a pixrect, an ops argument describing the operation to be 
performed, among others. This section describes these arguments in detail, and 
the results returned by the pixrect procedure. 

In this manual, the conventions listed in Table 3-1 are used in naming the argu- 
ments to pixrect operations. 



Argument Name Conventions 



Argument 


Meaning 


dsuffix 

ssuffix 

prefixx 

prefix? 

prefix* 

prefixh 


destination 

source 

offset to left edge of pixrect 
offset to top edge of pixrect 
width of pixrect (0 to 32767) 
height of pixrect (0 to 32767) 



The x and y values given to functions that operate on a pixrect must be within 
the boundaries of that pixrect, and be in the range 0 to 32767. 

Pixrect operations indicate an error condition in one of two ways, depending on 
the type of value the operation normally returns. Pixrect operations which return 
a pointer to a structure return NULL when they fail. For pixrect that return an 
integer status code, a return value of PIX_ERR (-1) indicates failure, while 0 
indicates the procedure completed successfully. The section describing each pix- 
rect procedure makes note of any exceptions to this convention. 

The multi-pixel operations described in the next section all use a uniform 
mechanism for specifying the operation which is to produce destination pixel 
values. This operation is given in the op argument and includes several com- 
ponents: 

□ A single constant source value may be specified as a color in bits 5 - 31 of 
the op argument. 

o A RasterOp function is specified in bits 1 - 4 of the op argument. 

□ The clipping which is normally performed by every pixrect operation may 
be turned off by setting the PIX_D0NTCLIP flag (bit 0) in the op. 

Structure of an op Argument 



, 

1 

1 




c 


color ; 

1 

l 

1 


opr 


i 

i 

P 



31 15 51 
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Specifying a RasterOp Four bits of the opr are used to specify one of the 16 distinct logical functions 

Function which combine monochrome source and destination pixels to give a mono- 

chrome result. This encoding is generalized to pixels of arbitrary depth by speci- 
fying that the function is applied to corresponding bits of the pixels in parallel. 
Some functions are much more common than others; the most useful are 
identified in Table 3-2. 

A convenient and intelligible form of encoding the function into four bits is sup- 
ported by the following definitions: 

. 

♦define PIX_SRC 0x18 
♦define PIX_DST 0x14 

♦define PIX_NOT(op) (OxlE & ('(op))) 

V J 



PIX_SRC and PIX_DST are defined constants, and PIX_NOT is a macro. 
Together, they allow the desired function to be specified by performing the 
corresponding logical operations on the appropriate constants. Note that 
PIX_N0T must be used in all RasterOp operations; the ones complement (“) 
operator will not work. 



A particular application of these logical operations allows definition of 
Pix_SET and Pix_CLR operations. The definition of the Pix_SET operation 
that follows is always true, and hence sets the result: 



— 




\ 


♦define PIX_SET (PIX_SRC 


| P IX_NOT ( P IX_SRC ) ) 









-J 



The definition of the PIX_CLR operation is always false, and hence clears the 
result: 



♦define PIX_CLR (PIX_SRC & PIX_NOT (PIX_SRC) ) 

J 



Other common RasterOp functions are defined in the following table: 



Table 3-2 Useful Combinations of RasterOps 



Op with Value 


Result 


PIX__SRC 

PIX_DST 

PIX_SRC | PIX_DST 
PIX_SRC & PIX_DST 
PIX_NOT (PIXJSRC) & PIX_DST 
PIX_NOT (PIXJDST) 

PIX_SRC ~ PIX_DST 


write same as source argument 

no-op same as destination argument 

paint OR of source and destination 

mask AND of source and destination 

erase AND destination with source negation 

invert area negate the existing values 

inverting paint XOR of source and destination 



microsystems 



Revision A of 9 May 1988 








Chapter 3 — Pixrect Operations 2 1 



Specifying a Color 



Controlling Clipping in a 
RasterOp 



Examples of Complete Op 
Argument Specification 



A single color value can be encoded in bits 5-3 1 of the op argument. The follow- 
ing macro supports this encoding: 

. 

♦define PIX_COLOR (color) ((color) « 5) 

k ./ 



Another macro extracts the color field from an encoded op: 



r 




\ 


♦define PIX_OPCOLOR (op) 


((op) » 5) 




V. 




J 



Note that the color is not part of the function component of the op argument and 
should never be part of an argument to PIX_NOT. 

The specified color is used by pixrect functions in two situations: 

1 . If the source pixrect argument is NULL, the rasterop source operand is taken 
to an infinite rectangle of pixels with the specified color. 

2. If the source pixrect has a depth of 1 bit and the destination pixrect has a 
greater depth, the rasterop source operand is the specified color for each "1" 
source pixel and zero for each "0" source pixel. A color of zero is treated as 
a special case; it is converted to the maximum pixel value for the destination 
pixrect. 

If the destination pixrect has a depth of 1 bit, any nonzero color value is treated 
as 1; for other depths less significant bits of the color value are used. If the desti- 
nation pixrect is 32 bits deep the encoded color is sign extended. 

Pixrect operations normally clip to the bounds of the operand pixrects. Some- 
times this can be done more efficiently by the client at a higher level. If the 
client can guarantee that only pixels which ought to be visible will be written, it 
may instruct the pixrect operation to bypass clipping checks, thus speeding its 
operation. This is done by setting the following flag in the op argument: 

♦define PIX_DONTCLIP Oxl 

k. j 



The result of a pixrect operation is undefined and may cause a memory fault if 
PIX_dontclip is set and the operation goes out of bounds. 

Note that the PIX_D0NTCLIP flag is not part of the function component of 
an op argument; it should never be part of an argument to PIX_NOT. 



A very simple op argument will specify that source pixels be written to a desti- 
nation, clipping to both operands: 



— 


N 


op - PIXJ3RC; 




N 


J 



A more complicated example could be used to flip the color of destination pixels 
between two values wherever pixels in a 1 bit source pixrect are set, with clip- 
ping disabled for maximum performance: 
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3.4. Creation and Pixrects are created by the procedures pr_open ( ) and mem_create ( ) , by 

Destruction of Pixrects the procedures accessed by the macro pr_region ( ) , and at compile-time by 

the macro mpr_stat ic ( ) . Pixrects are destroyed by the procedures accessed 
by the macros pr_destroy ( ) and pr_close ( ) . mem_create ( ) and 
mpr st at ic ( ) are discussed in Chapter 5; the rest of these are described here. 

Create a Primary Display Pixrect *pr_open (devicename) 

Pixrect char *devicename; 

The properties of a non-memory pixrect depend on an underlying UNIX device. 
Thus, when creating the first pixrect for a device you need to open it by a call to 
pr_open ( ) . The default device name for your display is / dev/ f b (f b stands 
for frame buffer). Any other device name may be used provided that it is a 
display device, the kernel is configured for it, it exists in the / dev directory, and 
it has pixrect support. For example; /dev/bwoneO, /dev/bwtwoO , 
/dev/cgoneO or /dev/cgtwoO all can exist on a Sun Workstation, and can 
be opened with pixrects. 

pr_open ( ) does not work for creating a pixrect whose pixels are stored in 
memory; that function is served by the procedure mem_create ( ) , discussed in 
Chapter 5. 

pr_open ( ) returns a pointer to a primary Pixrect structure which covers the 
entire surface of the named device. If it cannot, it returns NULL, and prints a 
message on the standard error output. 

Getting Screen Parameters In order to write portable programs, it is important to read the screen characteris- 

tics directly, rather than assuming them. The pixrect returned by pr_open ( ) 
contains this information. The two most important values are the dimensions of 
the screen, and the depth (number of bits) of each pixel. The code sample below 
opens a screen pixrect, then extracts the width, height and depth (in bits) of the 
screen. 




Revision A of 9 May 1988 





Chapter 3 — Pixrect Operations 23 



✓ 

tinclude <pixrect /pixrect hs.h> 
finclude <stdio.h> 

main ( ) 

{ 

Pixrect *screen, *pr_open ( ) ; 


\ 

include the proper definitions 


screen points to screen pixrect 


int height , width, depth; 


variables to make things clearer 


screen = pr open (" /dev/ fb” ) ; 


open the pixrect 


width = screen->pr size.x; 


extract the data in pr size; 


height = screen->pr_size . y ; 


width and height are in pixels 


depth = screen->pr depth; 


get depth in bits 


(void) printf ( "width = %d, height = %d, bits/pixel = %d0. 


width, height , depth) 


; display result 


(void)pr close (screen) ; 

} 


close the pixrect 

j 



Create Secondary Pixrect #define Pixrect *pr_region (pr, x, y, w, h) 

Pixrect *pr; 
int x, y, w, h; 

#define Pixrect *prs_region (subreg) 
struct pr_subregion subreg; 

Given an existing pixrect, it is possible to create another pixrect which refers to 
some or all of the pixels in the parent pixrect. This secondary pixrect is created 
by a call to the procedures invoked by the macros pr_region ( ) and 
prs_region ( ) . 

The existing pixrect is addressed by pr; it may be a pixrect created by 
pr_open ( ) , mem_create ( ) or mpr_static ( ) (a primary pixrect); or it 
may be another secondary pixrect created by a previous call to a region opera- 
tion. The rectangle to be included in the new pixrect is described by x, y, w and 
h in the existing pixrect; (x, y) in the existing pixrect will map to (0, 0) in the 
new one. prs_region ( ) does the same thing, but has all its argument values 
collected into the single structure subreg. Each region procedure returns a 
pointer to the new pixrect. If it fails, it returns null. 

If an existing secondary pixrect is provided in the call to the region operation, the 
result is another secondary pixrect referring to the underlying primary pixrect; 
there is no further connection between the two secondary pixrects. Generally, the 
distinction between primary and secondary pixrects is not important; however, 
no secondary pixrect should ever be used after its primary pixrect is destroyed. 
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Release Pixrect Resources 



3.5. Single-Pixel 
Operations 
Get Pixel Value 



Set Pixel Value 



#define pr_close (pr) 
Pixrect *pr; 

♦define pr_destroy (pr) 
Pixrect *pr; 



♦define prs_destroy (pr) 

Pixrect *pr; 

The macros pr_close (), pr_destroy ( ) and prs_destroy ( ) invoice 
device-dependent procedures to destroy a pixrect, freeing resources that belong 
to it. The procedure returns 0 if successful, P IX_ERR if it fails. It may be 
applied to either primary or secondary pixrects. If a primary pixrect is destroyed 
before secondary pixrects which refer to its pixels, those secondary pixrects are 
invalidated; attempting any operation but pr_destroy ( ) on them is an error. 
The three macros are identical; they are all defined for reasons of history and 
stylistic consistency. 



The next two operations manipulate the value of a single pixel. 

♦define pr_get (pr, x, y) 

Pixrect *pr; 
int x , y ; 

♦define prs_get (srcprpos) 
struct pr_j>rpos srcprpos; 

The macros pr_get and prs get invoke device-dependent procedures to 
retrieve the value of a single pixel, pr indicates the pixrect in which the pixel is 
to be found; x and y are the coordinates of the pixel. For pr s_get, the same 
arguments are provided in the single struct srcprpos. The value of the pixel is 
returned as a 32-bit integer, if the procedure fails, it returns P IX_ERR. 

♦define pr_put (pr, x, y, value) 

Pixrect *pr; 
int x, y, value; 

♦define prs_put (dstprpos, value) 
struct pr_prpos dstprpos; 
int value; 

The macros pr_put ( ) and pr s_put ( ) invoke device-dependent procedures 
to store a value in a single pixel, pr indicates the pixrect in which the pixel is to 
be found; x and y are the coordinates of the pixel. For pr s_put ( ) , the same 
arguments are provided in the single struct dstprpos. value is truncated on 
the left if necessary, and stored in the indicated pixel. If the procedure fails, it 
returns PIX ERR. 
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3.6. Multi-Pixel Operations The following operations all apply to multiple pixels at one time: pr_rop ( ) , 

pr_stencil ( ) , pr_replrop ( ) , pr_batchrop ( ) , pr_polygon_2 ( ) , 
and pr_vector ( ) . With the exceptions of pr vector ( ) and 
pr_jpolygon_2 ( ) , they refer to rectangular areas of pixels. They all use a 
common mechanism, the op argument described in the previous section, to 
specify how pixels are to be set in the destination. Appendix D. describes the 
pr_traprop ( ) curve rendering function. 



RasterOp Source to 
Destination 



♦define pr_rop (dpr, dx, dy, dw, dh, op, spr, sx, sy) 

Pixrect *dpr, *spr; 

int dx, dy, dw, dh, op, sx, sy; 

♦define prs_rop (dstregion, op, srcprpos) 
struct pr_subregion dstregion; 
int op; 

struct pr_prpos srcprpos; 

The pr_rop ( ) and prs rop ( ) macros invoke device-dependent procedures 
that perform the indicated raster operation from a source to a destination pixrect. 
dpr addresses the destination pixrect, whose pixels will be affected; (dx, dy) is 
the origin (the upper-left pixel) of the affected rectangle; dw and dh are the 
width and height of that rectangle, spr specifies the source pixrect, and 
(sx, sy) an origin within it. spr may be NULL, to indicate a constant source 
specified in the op argument, as described previously; in this case sx and sy arc 
ignored. The op argument specifies the operation which is performed; its con- 
struction is described in preceding sections. 

pr_rop () is the only pixrect function that can have its source and destination 
be overlapping areas of the same pixrect. Doing this with any other operation 
generates an error. 

For prs_rop ( ) , the dpr, dx, dy, dw and dh arguments are all collected in a 
pr_subregion structure. 

Raster operations are clipped to the source dimensions, if those are smaller than 
the destination size given. pr_rop ( ) procedures return PIX_ERR if they fail, 
0 if they succeed. 

Source and destination pixrects generally must be the same depth. The only 
exception allows monochrome pixrects to be sources to a destination of any 
depth. In this case, source pixels = 0 are interpreted as 0 and source pixels = 1 
are written as the color value from the op argument. If the color value in the op 
argument is 0, source pixels = 1 are written as the maximum value which can be 
stored in a destination pixel. 

See the example program in Figure 5-2 for an illustration of pr_rop ( ) . 



RasterOps through a Mask 
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#def ine pr_stencil (dpr, dx, dy, dw, dh, op, 
stpr, stx, sty, spr, sx, sy) 

Pixrect *dpr, *stpr, *spr; 

int dx, dy, dw, dh, op, stx, sty, sx, sy; 

#define prs_stencil (dstregion, op, stenprpos, srcprpos) 
struct pr_subregion dstregion; 
int op; 

struct pr_prpos stenprpos, srcprpos; 

The pr_stencil and prs_stencil macros invoke device-dependent pro- 
cedures that perform the indicated raster operation from a source to a destination 
pixrect only in areas specified by a third (stencil) pixrect. pr_stencil ( ) is 
identical to pr_rop ( ) except that the source pixrect is written through a stencil 
pixrect which functions as a spatial write-enable mask. The stencil pixrect must 
be a monochrome memory pixrect. The indicated raster operation is applied only 
to destination pixels where the stencil pixrect is non-zero. Other destination pix- 
els remain unchanged. The rectangle from (sx, sy) in the source pixrect spr is 
aligned with the rectangle from (stx, sty) in the stencil pixrect stpr, and 
written to the rectangle at (dx, dy) with width dw and height dh in the destina- 
tion pixrect dpr. The source pixrect spr may be null, in which case the color 
specified in op is painted through the stencil. Clipping restricts painting to the 
intersection of the destination, stencil and source rectangles. pr_stencil ( ) 
procedures return PI X_ERR if they fail, 0 if they succeed. 



Replicating the Source Pixrect pr_replrop (dpr, dx, dy, dw, dh, op, spr, sx, sy) 

Pixrect *dpr, *spr; 

int dx, dy, dw, dh, op, sx, sy; 

fdefine prs_replrop (dsubreg, op, sprpos) 
struct pr_subregion dsubreg; 
struct pr_prpos sprpos; 

Often the source for a raster operation consists of a pattern that is used repeat- 
edly, or replicated to cover an area. If a single value is to be written to all pixels 
in the destination, the best way is to specify that value in the color component 
of a pr_rop ( ) operation. But when the pattern is larger than a single pixel, a 
mechanism is needed for specifying the basic pattern, and how it is to be laid 
down repeatedly on the destination. 

The pr_replrop ( ) procedure replicates a source pattern repeatedly to cover a 
destination area, dpr indicates the destination pixrect. The area affected is 
described by the rectangle defined by dx, dy, dw, dh. spr indicates the source 
pixrect, and the origin within it is given by ( sx, sy). The corresponding 
prs_replrop ( ) macro generates a call to pr replrop ( ) , expanding its 
dsubreg into the five destination arguments, and sprpos into the three source 
arguments, op specifies the operation to be performed, as described above in 
Section 3.3, The Op Argument. 

The effect of pr_replrop ( ) is the same as though an infinite pixrect were 
constructed using copies of the source pixrect laid immediately adjacent to each 
other in both dimensions, and then a pr_rop ( ) was performed from that source 
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to the destination. For instance, a standard gray pattern may be painted across a 
portion of the screen by constructing a pixrect that contains exactly one tile of the 
pattern, and by using it as the source pixrect. 

The alignment of the pattern on the destination is controlled by the source origin 
given by ( sx, sy). If these values are 0, then the pattern will have its origin 
aligned with the position in the destination given by ( dx, dy). Another common 
method of alignment preserves a global alignment with the destination, for 
instance, in order to repair a portion of a gray. In this case, the source pixel 
which should be aligned with the destination position is the one which has the 
same coordinates as that destination pixel, modulo the size of the source pixrect. 
pr_replrop ( ) will perform this modulus operation for its clients, so it 
suffices in this case to simply copy the destination position (dx, dy) into the 
source position (sx, sy). 

pr replropO returns PIX_ERR if it fails, or 0 if it succeeds. Internally 
pr_replrop() may use pr_rop ( ) procedures. In this case, pr_rop ( ) 
errors are detected and returned by pr_replrop ( ) . 

Multiple Source to the Same 

Destination 



#define prs_batchrop (dstpos, op, items, n) 
struct pr_jorpos dstpos; 
int op, in- 
struct pr_prpos items []; 

Applications such as displaying text perform the same operation from a number 
of source pixrects to a single destination pixrect in a fashion that is amenable to 
global optimization. 

The pr_batchrop and prs_batchrop macros invoke device-dependent 
procedures that perform raster operations on a sequence of sources to successive 
locations in a common destination pixrect. items is an array of pr_prpos 
structures used by a pr_bat chrop ( ) procedure as a sequence of source pix- 
rects. Each item in the array specifies a source pixrect and an advance in x and 
y. The whole of each source pixrect is used, unless it needs to be clipped to fit 
the destination pixrect. The advance is used to update the destination position, 
not as an origin in the source pixrect. 

pr_batchrop ( ) procedures take a destination, specified by dpr, dx and dy, 
or by dstpos in the case of prs_batchrop ( ) ; an operation specified in op, 
as described in Section 3.3. and an array of pr_prpos addressed by the argu- 
ment items, and whose length is given in the argument n. 

The destination position is initialized to the position given by dx and dy . Then, 
for each item, the offsets given in pos are added to the previous destination 
position, and the operation specified by op is performed on the source pixrect 
and the corresponding rectangle whose origin is at the current destination posi- 
tion. Note that the destination position is updated for each item in the batch, and 
these adjustments are cumulative. 




fdefine pr_batchrop (dpr, dx, dy, op, items, n) 

Pixrect *dpr; 

int dx, dy, op, n; 

struct pr__prpos items []; 



Revision A of 9 May 1988 





28 Pixrect Reference Manual 



Draw Vector 



Draw Textured Polygon 



The most common application of pr_bat chrop ( ) procedures is in painting 
text; additional facilities to support this application are described in Chapter 4. 
Note that the definition of pr_bat chrop ( ) procedures supports variable-pitch 
and rotated fonts, and non-Roman writing systems, as well as simpler text. 

pr_bat chrop ( ) procedures return PIX_ERR if they fail, 0 if they succeed. 
Internally pr_bat chrop ( ) may use pr_rop ( ) procedures. In this case, 
pr_rop ( ) errors are detected and returned by pr_bat chrop ( ) . 



♦define pr_vector (pr, xO, yO, xl, yl, op, value) 
Pixrect *pr; 

int xO, yO, xl, yl, op, value; 



♦define prs_vector (pr, posO, posl, op, value) 

Pixrect *pr; 

struct pr_pos posO, posl; 
int op, value; 

The pr_vector and prs_vector macros invoke device-dependent pro- 
cedures that draw a vector one unit wide between two points in the indicated pix- 
rect. pr_vector() procedures draw a vector in the pixrect indicated by pr, 
with endpoints at (xO, yO) and(xl, yl), or at posO and posl in the case of 
pr s_vector ( ) . Portions of the vector lying outside the pixrect are clipped as 
long as PIX_D0NTCLIP is 0 in the op argument. The op argument is con- 
structed as described in Section 3.3. and value specifies the resulting value of 
pixels in the vector. If the color in op is non-zero, it takes precedence over the 
value argument. 

Any vector that is not vertical, horizontal or 45 degree will contain jaggies. This 
phenomenon, known as aliasing, is due to the digital nature of the bitmap screen. 
It can be visualized by imagining a vertical vector. Displace one endpoint hor- 
izontally by a single pixel. The resulting line will have to jog over a pixel at 
some point in the traversal to the other endpoint. Balancing the vector guaran- 
tees that the jog will occur in the middle of the vector. pr_vect or ( ) draws 
balanced vectors. (The technique used is to balance the Bresenham error term). 
The vectors are balanced according to their endpoints as given and not as 
clipped, so that the same pixels will be drawn regardless of how the vector is 
clipped. 

See the example program in Figure 1-2 for an illustration of pr_vector ( ) . 



pr_polygon_2 (dpr, dx, dy, nbnds, npts, vlist, op, spr, sx, s] 

Pixrect *dpr, *spr; 

int dx, dy 

int nbnds, npts[]; 

struct pr_jpos *vlist; 

int op, sx, sy; 



The pr_polygon_2 ( ) function performs a raster operation on a polygonal 
area of the destination pixrect. The source can be a pattern or a constant color 
value. 
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The destination polygon is described by nbnds, npts and vlist. nbnds is 
the number of individual closed boundaries (vertex lists) in the polygon. A com- 
plex polygon may have one boundary for its exterior shape and several boun- 
daries delimiting interior holes. The boundaries may intersect themselves or 
each other. Only those destination pixels having an odd winding number are 
painted. That is, if any line connecting a pixel to infinity crosses an odd number 
of boundary edges, the pixel will be painted. 

For each of the nbnds boundaries, npts specifies the number of points in the 
boundary. The vlist array contains the boundary points for all of the boun- 
daries, in order. The total number of points in vlist is equal to the sum of the 
nbnds elements in the npts array. pr_polygon_2 ( ) automatically joins the 
last point and first point to close each boundary. If any boundary has fewer than 
3 points, pr_polygon_2 ( ) returns PIX_ERR. 

The destination coordinates dx, and dy are added to each point in vlist, so the 
same vlist can be used to draw polygons in different destination locations. 

If the source pixrect spr is non-null, it is replicated in the x and y directions to 
cover the entire destination area. The point ( sx, sy) in this extended source 
pixrect is aligned with the point ( dx, dy) in the destination pixrect. 

Polygons drawn by pr_polygon_2 ( ) are semi-open in the sense that on some 
of the edges, pixels are not drawn where a vector drawn with same coordinates 
would go. The reason is to allow identical polygons (same size and orientation) 
to exactly tile the destination pixrect with no gaps and no overlaps. 

In Figure 3-3 the edges AB and DA are drawn, whereas edges BC and CD aren’t. 
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Figure 3-2 Example Program using pr_jpolygon_2 ( ) 



#include <pixrect/pixrect_hs . h> 

fdefine CENTERX (pr) ( (pr) ->p r__size . x / 2) 
#def ine NULLPR ((Pixrect *) 0) 

static struct pr_pos 
/* 45 degrees */ 



vlistO [4] = { 


{0, 


0}, 


{ 


71, 


-71}, 


{141, 


0}, 


{ 71, 


71} }, 


/* 30 degrees 


*/ 


















vlistl [4] = { 


{0, 


0}, 


{ 


r- 

00 


-50}, 


{137, 


37}, 


{ 50, 


87} }, 


/* 0 degrees * 


/ 


















vlist2[4] = { 


{0, 


0}, 


H 

o 

o 


0}, 


{100, 


o 

o 

H 


{ o. 


100} }, 


/* -30 degrees 


*/ 


















vlist3 [4] — { 


{0, 


0}, 


{ 


00 


50}, 


{ 37, 


137}, 


{-50, 


87} }; 



Pixrect *pr; 

static int npts[l] - { 4 }; 

if ( ! (pr = pr_open (" /dev/fb”) ) ) 
exit (1); 

pr_polygon_2 (pr, CENTERX (pr) , 100, 1, npts, vlistO, 

PIX SET, NULLPR, 0, 0); 

pr_polygon_2 (pr, CENTERX (pr) , 300, 1, npts, vlistl, 
P IX SET , NULLPR, 0, 0); 

pr j>olygon_2 (pr, CENTERX (pr) , 500, 1, npts, vlist2, 

PIX__SET, NULLPR, 0, 0); 

pr__polygon_2 (pr, CENTERX (pr) , 700, 1, npts, vlist3, 
PIX_SET, NULLPR, 0, 0) ; 

pr__close (pr) ; 

exit (0) ; 
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Figure 3-3 Four Polygons Drawn with pr_polygon_2 () 




Draw Textured or Solid Lines #define pr_line(pr, xO, yO, xl, yl, brush, tex, op) 
with Width Pixrect *pr; 

int xO, yO, xl, yl; 
struct pr_brush *brush; 
struct pr_texture *tex; 
int op; 

The pr_line macro draws a textured line based on the Bresenham line drawing 
algorithm, using a pen-up, pen-down approach. The programmer can define an 
pattern (of arbitrary length), or use a predefined default pattern (dash-dot, dotted, 
etc.). All pattern segments (and their corresponding offsets) can automatically 
adjust, according to the angle at which the line is drawn. 



If the brush pointer is NULL, or if 
the width is 0 or 1, a single width 
vector is drawn. 



The line is drawn in the pixrect indicated by pr , with endpoints at (xO , y 0) 
and (xl , y 1). The brush field is a pointer to a structure of type prjorush 
which holds the width of the line segments to be rendered. The pr_brush 
structure is defined in the header file <pixrect/pr_line . h> as follows: 
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If the tex pointer is NULL, a solid vector is drawn. The tex field is a pointer 
to a structure of type pr_texture. The pr_texture structure is defined in 
the header file <pixrect /pr_line . h> as follows (fields that begin with the 
prefix res_ are reserved for program internals, and are not user-definable): 




pattern is a pointer to an array of short integers which contain the length of 
each segment in the pattern. The lengths are in units of pixels. If the line is 
drawn at an angle, the lengths drawn are automatically adjusted (if the given- 
pattern field set to 0) to correspond to the length of the pattern if a horizontal 
or vertical line was drawn. This array must be null-terminated. The first seg- 
ment of the pattern array is assumed to be pen-down, and following segments 
alternate. 



The addresses of the following predefined pattern arrays may be stored in the 
pattern field of the texture structure as well: 




The programmer-defined elements of the pattern array are not altered within 
the routine, allowing multiple calls using the same pattern, of f set is an 
integer offset into the pattern, specified in pixels. Since the first segment of the 
pattern array is assumed to be pen-down, you must specify an offset to 
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Draw Textured or Solid 
Polylines with Width 



start on a pen-up segment, offset is adjusted according to the angle at which 
the line is drawn if the original pattern was adjusted (dependent upon the 
givenpattern bit, described later). Because of integer approximation, the 
adjusted offset could vary plus or minus one pixel from the exact adjusted 
offset. 

In the options bit fields, if startpoint is set, the first point is always drawn, 
and if endpoint is set, the last point is drawn; if these are not specified, the 
line will be drawn with no extra pixels set. The balanced bit field effectively 
centers the pattern within the line by computing an offset into the pattern. If the 
givenpattern bit is set, the pattern is drawn without true length correction, at 
any angle; this increases performance. However, the pattern of radiating lines 
from a common center will form concentric squares instead of circles. If the 
givenpattern bit is not set, the segment length of each element of the pattern 
is adjusted according to the angle at which the line is drawn. The true (angle- 
dependent) segment lengths are computed for one period of the pattern, using an 
incremental algorithm which approximates the formula: 

angle _pattern_length = given jpatternjength * cos (angle) 
where all units are in pixels, and angle is measured from the positive r-axis. 

Since the algorithm angle-corrects for one period of the pattern, the longer its 
period, the more exact the results are. 

The op argument specifies the raster operations used to produce destination pixel 
values and color. 

pr_polyline (dpr, dx, dy, npts, ptlist, mvlist, brush, tex, op) 

Pixrect *dpr; 

int dx, dy, npts; 

struct pr_j?os *ptlist; 

u_char *mvlist; 

struct pr_brush *brush; 

struct pr_texture *tex; 

int op ; 

pr__polyline draws a polyline, or a series of disjoint polylines, using the 
features available in pr_line. The polyline is drawn in the destination pixrect 
indicated by dpr, with dx and dy being the offset into the destination pixrect 
for vertices to be translated in x and y, respectively, npt s is the number of ver- 
tices in the polyline (which is always the number of lines plus 1). The ptlist 
field is an array of npts structures of type pr_pos (which hold vertices). The 
mvlist field is a pointer to an array of npts elements in which if any element 
after the first is non-zero, a segment is not drawn to that vertex. The first element 
of the mvlist array controls whether the polyline(s) are automatically closed; if 
set, each continuous polyline is closed. If disjoint polylines are not desired (no 
mvlist is specified), the constants POLY_CLOSE and POLY_DONTCLOSE 
determine this behavior. POLY CLOSE and POLY_DONTCLOSE are defined as 
follows: 

— 

# define POLY_CLOSE ( (u_char *) 1) 

#def ine POLY_DONTCLOSE ( (u_char *) 0) 

V > 
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Draw Multiple Points 



3.7. Colormap Access 



Get Colormap Entries 



The brush field is a pointer to a structure of type pr_brush, and the t ex field 
is a pointer to a structure of type pr_texture. If the tex pointer is null, a 
solid vector is drawn. If the brush structure is null, single-width vectors are 
drawn, op specifies the raster operations used to produce destination pixel 
values and color, brush and tex are described in detail under pr_line. 

pr_jpolypoint (dpr, dx, dy, npts, ptlist, op) 

Pixrect *dpr; 
int dx, dy, npts; 
struct pr_pos *ptlist; 
int op; 

The pr_jpolypoint routine draws an array of points on the screen under the 
control of the op argument. The array of points is drawn in the destination pix- 
rect dpr, with an offset specified by the arguments dx and dy. Npt s is the 
number of points to be rendered, and pt li st is a pointer to an array of struc- 
tures of type pr_pos, which hold the vertices for each point. Color is encoded 
in the op argument. Portions of the array outside the pixrect are clipped unless 
the PIX_D0NTCLIP flag is set in the op argument. 

A colormap is a table which translates a pixel value into 8 -bit intensities in red, 
green, and blue. For a pixrect of depth n, the corresponding colormap will have 
2 n entries. The two most common cases are monochrome (two entries) and color 
(256 entries). Memory pixiects do not have colormaps. 

Sun grayscale workstations normally use the red video signal to drive the moni- 
tor. However, when writing an application to run on a grayscale workstation it is 
a good idea to load the red, green, and blue components of each colormap entry 
with the same value. This will ensure that the application will also mn properly 
on a color workstation. 

♦define pr_getcolormap (pr, index, count, red, green, blue) 

Pixrect *pr; 

int index, count ; 

unsigned char red[], green[], blue[]; 

♦define prs_getcolormap (pr, index, count, red, green, blue) 

Pixrect *pr; 

int index, count ; 

unsigned char red[], green [], blue[]; 

The macros pr_get colormap and prs_getcolormap invoke device- 
dependent procedures to read all or part of a colormap into arrays in memory. 

These two macros have identical definitions; both are defined to allow consistent 
use of one set of names for all operations. 

pr identifies the pixrect whose colormap is to be read; the count entries start- 
ing at index (zero origin) are read into the three arrays. 

For monochrome pixrects the same value is read into corresponding elements of 
the red, green and blue arrays. These array elements will have their bits 
either all cleared, indicating black, or all set, indicating white. By default. 
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Set Colormap Entries 



Inverted Video Pixrects 



the Oth ( background) element is white, and the 1st (foreground) element is black. 
Colormap procedures return (-1) if the index or count are out of bounds, and 0 if 
they succeed. 



#define pr_jDut colormap (pr, index, count, red, green, blue) 

Pixrect *pr; 

int index, count; 

unsigned char red[], green [], blue[]; 

tdefine prs _j?ut colormap (pr, index, count, red, green, blue) 

Pixrect *pr; 

int index, count; 

unsigned char red[], green [], blue[]; 

The macros pr_jput colormap and pr s_j?ut colormap invoke device- 
dependent procedures to store from memory into all or part of a colormap. These 
two macros have identical definitions; both are defined to allow consistent use of 
one set of names for all operations. The count elements starting at index 
(zero origin) in the colormap for the pixrect identified by pr are loaded from 
corresponding elements of the three arrays. For monochrome pixrects, the only 
value considered is red [ 0 ] . If this value is 0, then the pixrect will be set to a 
dark background and light foreground. If the value is non-zero, the foreground 
will be dark, e.g. black-on-white. Monochrome pixrects are dark-on-light by 
default. 

Note: Full functionality of the colormap is not supported for monochrome pix- 
rects. Colormap changes to monochrome pixrects apply only to subsequent 
operations whereas a colormap change to a color device instantly changes all 
affected pixels on the display surface. 

pr_blackonwhite (pr, min, max) 

Pixrect *pr; 
int min, max; 

pr_whiteonblack (pr, min, max) 

Pixrect *pr; 
int min, max; 

pr^reversevideo (pr, min, max) 

Pixrect *pr; 
int min, max; 

Video inversion is accomplished by manipulation of the colormap of a pixrect. 
The colormap of a monochrome pixrect has two elements. The procedures 
pr_blackonwhite, pr_whiteonblack and pr_reversevideo pro- 
vide video inversion control. These procedures are ignored for memory pixrects. 

In each procedure, pr identifies the pixrect to be affected; min is the lowest 
index in the colormap, specifying the background color, and max is the highest 
index, specifying the foreground color. These will most often be 0 and 1 for 
monochrome pixrects; the more general definitions allow colormap-sharing 
schemes. 
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“Black-on- white” means that zero (background) pixels will be painted at full 
intensity, which is usually white. pr_blackonwhite ( ) sets all bits in the 
entry for colormap location min and clears all bits in colormap location max. 

“White-on-black” means that zero (background) pixels will be painted at 
minimum intensity, which is usually black. pr_whiteonblack () clears all 
bits in colormap location min and sets all bits in the entry for colormap location 
max. 

pr_re verse video ( ) exchanges the min and max color intensities. 

Note: These procedures are intended for global foreground/background control, 
not for local highlighting. For monochrome frame buffers, subsequent opera- 
tions will have inverted intensities. For color frame buffers, the colormap is 
modified immediately, which affects everything in the display. 

3.8. Attributes for Bitplane In a color pixrect, it is often useful to define bitplanes which may be manipulated 
Control independently; operations on one plane leave the other planes of an image unaf- 

fected. This is normally done by assigning a plane to a constant bit position in 
each pixel. Thus, the value of the i 1 * 1 bit in all the pixels defines the i* bitplane 
in the image. It is sometimes beneficial to restrict pixrect operations to affect a 
subset of a pixrect’s bitplanes. This is done with a bitplane mask. A bitplane 
mask value is stored in the pixrect’s private data and may be accessed by the 
attribute operations. 

Get Plane Mask Attributes fdefine pr_getattributes (pr, planes) 

Pixrect *pr; 
int *planes; 

fdefine prs_getat tributes (pr, planes) 

Pixrect *pr; 
int *planes; 

The macros pr_getattributes ( ) and prs_getattributes ( ) invoke 
device-dependent procedures that retrieve the mask which controls which planes 
in a pixrect are affected by other pixrect operations, pr identifies the pixrect; its 
current bitplanes mask is stored into the word addressed by planes. If 
planes is NULL, no operation is performed. 

The two macros are identically defined; both are provided to allow consistent use 
of the same style of names. 

Put Plane Mask Attributes idefine pr_putattributes (pr, planes) 

Pixrect *pr; 
int *planes; 

tdefine prs_putattributes (pr, planes) 

Pixrect *pr; 
int *planes; 

The macros pr_jputattributes ( ) and prs_put attributes () invoke 
device-dependent procedures that manipulate a mask which controls which 
planes in a pixrect are affected by other pixrect operations. The two macros are 
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identically defined; both are provided to allow consistent use of the same style of 
names. 

pr identifies the pixrect to be affected. The planes argument is a pointer to a 
bitplane write-enable mask. Only those planes corresponding to mask bits hav- 
ing a value of 1 will be affected by subsequent pixrect operations. If planes is 
NULL, no operation is performed. 

Note: If any planes are masked off by a call to pr_putattr ibutes ( ) , no 
further write access to those planes is possible until a subsequent call to 
pr_put at tribute s ( ) unmasks them. However, these planes can still be 
read. 



3.9. Plane Groups A plane group is a subset of a frame buffer pixrect. Each plane group is a collec- 

tion of one or more related bit planes with stored state (plane mask, color map, 
etc.). Each pixrect has a current plane group which is the target of attribute, 
color map, and rendering operations. 



A plane group is described by a small constant in the header file 
<pixrect/pr_planegroups .h>: 



— 
#def ine 


P I XP G_CURRENT 


0 




#def ine 


PIXPG MONO 


1 




#def ine 


PIXPG_8BIT_COLOR 


2 




#def ine 


P IXPG_OVERLAY__ENABLE 


3 




#define 


PIXPG__OVERLAY 


4 




V 









Plane group 0 is the currently active plane group for the pixrect. 

A plane group is encoded as a 7-bit field in the pixrect attribute word. 



Determine Supported Plane ngroups = pr_available_plane_groups (pr, maxgroups, groups); 

Groups Pixrect *pr; 

int maxgroups; 

char groups [maxgroups] 

pr_available_plane_groups provides a means by which you determine 
which plane groups are supported by the machine you are working on. 
pr_available_plane_groups fills the character array groups with true 
(1) values for the plane groups implemented by the pixrect pr. The entry for the 
current plane group (groups [ 0 ] ) array is always set to false (0). The size of 
groups is passed to the function as maxgroups to avoid overwriting the end 
of the array. 

pr_available_plane_groups returns the index of the highest-numbered 
implemented plane group plus one. 



Get Current Plane Group group = pr_getjplane_group (pr) ; 

Pixrect *pr; 

pr_get_plane_group returns the current plane group number for the pixrect 
pr . If the current plane group is unknown, the function returns 
PIXPG CURRENT. 
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Set Plane Group and Mask 



3.10. Double Buffering 



Get Double Buffering 
Attributes 



void pr_set_plane_group (pr, group); 

Pixrect *pr; 
int group; 

void pr_set_planes (pr, group, planes) 

Pixrect *pr; 
int group ; 
int planes; 

pr_set_plane_group sets the current plane group for the pixrect pr to the 
value given by group. If this plane group is P IXPG_CURRENT or unimple- 
mented, pr_set_plane_group does nothing. 

The pr_set_planes function is equal to a pr_set_plane_group (pr , 
group) followed by pr_putattributes (pr, splanes). planes 
contains a bitplane write-enable mask. Only those planes corresponding to mask 
bits having a value of 1 will be affected by subsequent pixrect operations. How- 
ever, the other planes can still be read. 

Some frame buffers have double buffering support implemented in hardware. 
Two pixrect commands, pr_dbl_get ( ) , and pr_dbl_set ( ) allow you to 
inquire about and control a double-buffered display device. The pixrect interface 
assigns two names to the buffers in the display; PR_DBL_A for one, and 
PRJDBL_B for the other. 

A buffer can be displayed, read, or written. When a buffer is displayed, its 
stored image is shown on the screen. If the software requests that the other 
buffer be displayed, the hardware doesn’t switch to the new buffer until the next 
vertical retrace of the screen. This prevents any flicker from showing on the 
screen during the change between buffers. A buffer can be read or written, using 
pixrect commands, at any time. 

state = pr_dbl_get (pr, attribute) 

Pixrect *pr; 
int attribute; 

This function shows the current attributes of the double buffer. You can inquire 
about the state of the display device by executing pr_dbl_get with a particu- 
lar attribute value, then examining the function’s return value. The legal attri- 
butes are listed below: 



— 

♦define 


PR DBL AVAIL 


1 




# define 


PR DBL DISPLAY 


2 




#def ine 


PR_DBL_WRITE 


3 




#def ine 


PR_DBL_READ 


4 













The PR_DBL_AVAIL returns PR_DBL_EXISTS if display device has hardware 
double buffering capacity; otherwise, it returns NULL. The other attributes indi- 
cate which buffer on the device is being displayed, which can be written to, etc. 
The possible state values for these attributes is given below: 
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♦define PR_DBL_A 2 
♦define PR_DBL_B 3 
♦define PR_DBL_BOTH 4 
♦define PR DBL NONE 5 



Not all return values are possible with each attribute. The values that can be 
returned for a given attribute a shown in the table below: 

Table 3-3 pr_dbl_get ( ) Attributes 



Attribute 


Possible Values Returned 


PR_DBL_AVA I L 
PR_DBL_D I SPLAY 
PR_DBL_WRITE 
PRJDBLJREAD 


PR__DBL_EXISTS 
PR_DBL_A, PR_DBL_B 

PR_DBL_A, PR_DBL_B, PR_DBL_BOTH, P R_DBL_NONE 
PR_DBL_A, PR_DBL_B 



Set Double Buffering void pr_dbl_set (pr, attribute_list) 

Attributes Pixrect *pr; 

int *attribute_list; 

The pr_dbl_set ( ) function changes the state of the double buffering display. 
It controls the buffer being displayed, and selects the buffer(s) affected by pixrect 
reads and writes. The possible attributes for pr_dbl_set ( ) are given below: 



— 
#def ine 


PR_DBL_D ISP LAY 


2 




#def ine 


PR DBL WRITE 


3 




#def ine 


PR_DBL_READ 


4 




#def ine 


PR__DBL_DISPLAY_DONTBLOCK 


5 










J 



An attribute list is an integer array consisting of pairs of attributes and the value 
the attribute should be set to. The last element of the array should be zero. If the 
display is already in the state requested, the function simply returns. 

If the PR_DBL_DISPLAY attribute is in the list, then the function may block for 
up to a single video frame’s time (15 ms), waiting for the next vertical retrace. 
This insures that the next pixrect operation won’t alter the buffer while it’s still 
being displayed. Applications that won’t write to the buffer for at least 15 ms 
after changing the displayed buffer, and who need maximum throughput can use 
PR_DBL_DlSPLAY_DONTBLOCK. This attribute changes the display without 
blocking the process until the next vertical retrace. 

NOTE Programmers should use PR_DBL_DISPLAY_DONTBLOCK with caution. If 
the application starts writing too early, it will modify the buffer while it is still 
being displayed. 

The values that can be paired with the attributes are shown below: 
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r 

#def ine 


PR DBL A 


2 


X 


#def ine 


PR_DBL_B 


3 




#def ine 


PR_DBL_BOTH 


4 




v 






J 



Not all of the values can be paired with all of the attributes; the allowed pairings 
are shown in the table below: 

Table 3-4 pr_dbl_set() Attributes 



Attribute 


Possible Values to Set 


PR_DBL_WRI TE 

PR_DBL__READ j 

PR_DBL_DI SPLAY_DONTBLOCK 
PR_DBL_DISPLAY 


PR_DBL_A, PR_DBL_B, PR_DBL_BOTH 
PR_DBL_A, PR__DBL_B 
PR_DBL_A, PR__DBL_B 
PR_DBL_A, PR_DBL_B 



3.11. Efficiency For maximum execution speed, remember the following points when you write 

Considerations pixrect programs: 

□ pr_get and pr_put ( ) are relatively slow. For fast random access of pix- 
els it is usually faster to read an area into a memory pixrect and address the 
pixels directly. 

□ pr_rop ( ) is fast for large rectangles. 

□ pr_vector ( ) is fast. 

□ functions run faster when clipping is turned off. Do this only if you can 
guarantee that all accesses are within the pixrect bounds. 

□ pr_rop ( ) is three to five times faster than pr_stencil ( ) . 

□ pr_batchrop () cuts down the overhead of painting many small pixrects. 

a For small standard shapes pr rop ( ) should be used instead of 
pr_polygon_2 ( ) . 

□ pr_polyline () is an efficient way to draw a series of vectors. 

Q pr_polypoint ( > is faster than a series of pr_put s ( ) or single pixel 
pr_rops ( ) . It is useful for implementing new primitives such as curves. 

□ The PR_DBL_DISPLAY_DONTBLOCK attribute of pr_dbl_set ( ) , if 
used appropriately, can speed up animation sequences. 
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Text Facilities for Pixrects 



The Pixrect library contains higher-level facilities for displaying text. These 
facilities fall into two main categories: a standard format for describing fonts and 
character images, including routines for processing them; and a set of routines 
that take a string of text and a font, and handle various parts of painting that 
string in a pixrect. 



4.1. Pixfonts and Pixchars 



f 




struct pixchar { 




struct pixrect *pc_pr; 




struct pr_pos pc home; 




struct pr_pos pc_adv; 

} ; 




v 





The pixchar structure defines the format of a single character in a font. The 
actual image of the character is a pixrect (a separate pixrect for each character) 
addressed by pcjr. The entire pixrect gets painted. Characters that do not 
have a displayable image will have NULL in their entry in pc_pr. pc_home is 
the origin of pixrect pc_pr (its upper left comer) relative to the character origin. 
A character’s origin is the leftmost end of its baseline, that is the lowest point on 
characters without descenders. Figure 4-1 illustrates the pc_pr origin and the 
character origin. 

The leftmost point on a character is normally its origin, but kerning or mandatory 
letter spacing may move the origin right or left of that point, pc adv is the 
amount the destination position is changed by this character, that is, the amounts 
in pc_adv added to the current character origin will give the origin for the next 
character. While normal text only advances horizontally, rotated fonts may have 
a vertical advance. Both are provided for in the font. 



/ 


a 


typedef struct pixfont { 




struct pr_size pf_def aultsize ; 




struct pixchar pf_char [256] ; 




} Pixfont; 






y 



The Pixfont structure contains an array of pixchars, indexed by the charac- 
ter code; it also contains the size (in pixels) of its characters when they are all the 
same. If the size of a font’s characters varies in one dimension, that value in 
pf_def ault size will not have anything useful in it; however, the other may 
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still be useful. Thus, for non-rotated variable-pitch fonts, 

pf_def ault size . y will still indicate the unleaded interline spacing for that 

font. 

Figure 4-1 Character and pc_pr Origins 




character 

baseline 



4.2. Operations on Pixfonts The commands listed below allow you to load a font to display. A font must be 

loaded before using a text operation. 

Load a Font Pixfont *pf_open (name) 

char *name; 

pf _open ( ) returns a pointer to a shared copy of a font in virtual memory. A 
NULL is returned if the font cannot be opened. The path name of the font file 
should be specified, for example: 

myfont = pf_open ( "/usr/lib/fonts/f ixedwidthfont. s/screen. r. 7”) ; 
v / 



name should be in the format described in vfont( 5): the file is converted to pix- 
font format, allocating memory for its associated structures and reading in the 
data for it from disk. The utility font edit (1) is a font editor for designing 
pixel fonts in vfont( 5) format. 

The data from a small selection of commonly used fonts is compiled into the pix- 
rect library. The names of these built-in fonts are checked against the last com- 
ponent of the name. To guarantee that the font is loaded from the disk file 
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instead, use pf_open_private ( ) instead of pf_open ( ) . 

Load Private Copy of Font Pixf ont *pf_open_private (name) 

char *name; 

pf _open ( ) returns a pointer to a private copy of a font in virtual memory. A 
NULL is returned if the font cannot be opened. 

Default Fonts Pixfont *pf_default () 

The procedure pf_de fault performs the same function for the system default 
font, normally a fixed-pitch, 16-point sans serif font with upper-case letters 12 
pixels high. If the environment parameter DEFAULTJFONT is set, its value will 
be taken as the name of the font file to be opened by pf_de fault ( ) . 

Close Font pf_close (pf ) 

Pixfont *pf; 

When a client is finished with a font, it should call pf_clo se ( ) to free the 
memory associated with it pf should be a font handle returned by a previous 
call to pf_open ( ) or pf_def ault ( ) . 

4.3. Text Functions The following functions manage various tasks involved in displaying text. 

Pixrect Text Display pf_text (where, op, font, text) 

struct pr_jprpos where; 
int op; 

Pixfont *font; 
char *text; 

Characters are written into a pixrect with the pf_t ext ( ) procedure, where is 
the destination for the start of the text (nominal left edge, baseline; see Section 
4.1) op is the raster operation to be used in writing the text, as described in Sec- 
tion 3.3, The Op Argument, font is a pointer to the font in which the text is to 
be displayed; and text is the actual null-terminated string to be displayed. The 
color specified in the op specifies the color of the ink. The background of the 
text is painted 0 (background color). 

Transparent Text pf_ttext (where, op, font, text) 

struct pr_j?rpos where; 
int op; 

Pixfont *font; 
char *text; 

pf ttext paints “transparent” text: it doesn’t disturb destination pixels in 
blank areas of the character’s image. The arguments to this procedure are the 
same as for pf text ( ) . The characters’ bitmaps are used as a stencil, and the 
color specified in op is painted through the stencil. 

For monochrome pixrects, the same effect can be achieved by using PIX_SRC 
I P IX_DST as the function in the op; this procedure is for color pixrects. 
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Auxiliary Pixfont Procedures struct pr_size pf_textbatch (where , lengthp, font, text) 

struct pr_j?rpos where []; 
int * lengthp; 

Pixfont *font; 
char *text; 

struct pr_size pf_t ext width ( len, font, text) 
int len; 

Pixfont *font; 
char *text; 

pf_textbatch ( ) is used internally by pf_text ( ) ; it constructs an array of 
pr_pos structures and records its length, as required by bat chrop (see Sec- 
tion 3.6). where should be the address of the array to be filled in, and 
lengthp should point to a maximum length for that array, text addresses the 
null- terminated string to be put in the batch, and font refers to the Pixfont to 
be used to display it. When the function returns, lengthp will refer to a word 
containing the number of pr_po s structures actually used for text . The 
pr__size returned is the sum of the pc_adv fields in their pixchar struc- 
tures. 

pf_textwidth ( ) returns a pr_size that is computed by taking the product 
of len, is the number of characters, and pc adv, the width of each character. 

Text Bounding Box pf_textbound (bound, len, font, text) 

struct pr_subregion *bound; 
int len; 

Pixfont *font; 
char *text; 

pf_textbound may be used to find the bounding box for a string of characters 
in a given font. bound->pos is the top-left comer of the bounding box, 
bound->size . x is the width, and bound->size . y is the height. 
bound->pr is not modified. bound->pos is computed relative to the loca- 
tion of the character origin (base point) of the first character in the text. 

Unstructured Text pr_text(pr, x, y, op, font, text) 

Pixrect *pr; 
int x, y, op; 

Pixfont *font; 
char *text; 

pr_ttext (pr, x, y, op, font, text) 

Pixrect *pr; 
int x, y, op; 

Pixfont *font; 
char *text; 

These unstructured text functions correspond to the Pixwin functions 
pw_text ( ) and pw_ttext ( ) . pr s_text ( ) and prs_ttext ( ) macros 
are also provided, although they are identical to pf_text ( ) and 
pf_ttext ( ) , respectively. 
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4.4. Example Here is an example program that writes text on the display surface with pixel 

fonts. 

Figure 4-2 Example Program using Text 



finclude <pixrect/pixrect_hs . h> 

main ( ) 

{ 

Pixrect *pr; 

Pixfont *pf; 

if (! (pr = pr_open <"/dev/fb" ) ) | j 

! (pf = pf__open ("/usr/lib/fonts/f ixedwidthf onts/screen . r . 12") ) ) 
exit ( 1) ; 

pr_text (pr, 400, 400, PIX_SET, pf, "This is a string.") ; 

pr_close (pr ) ; 
pf__close (pf ) ; 
exit (0) ; 
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Memory Pixrects 

5.1. The mpr_data Structure 

Example 

5.2. Creating Memory Pixrects 

Create Memory Pixrect 

Create Memory Pixrect from an Image 
Example 

5.3. Static Memory Pixrects 

5.4. Pixel Layout in Memory Pixrects 

5.5. Using Memory Pixrects 






Memory Pixrects 



Memory pixrects store their pixels in memoiy, instead of displaying them on 
some display, are similar to other pixrects but have several special properties. 
Like all other pixrects, their dimensions are visible in the pr_size and 
pr_depth elements of their Pixrect structure, and the device-dependent 
operations appropriate to manipulating them are available through their 
pr_ops. Beyond this, however, the format of the data which describes the par- 
ticular pixrect is also public: pr_data will hold the address of an mpr_data 
struct described below. Thus, a client may construct and manipulate memory 
pixrects using non-pixrect operations. There is also a public procedure, 
mem_create ( ) , which dynamically allocates a new memory pixrect, and a 
macro, mpr_stat ic ( ) , which can be used to generate an initialized memory 
pixrect in the code of a client program. 

5.1. The mpr_data 

Structure 



The pr_dat a element of a memory pixrect points to an mpr_data struct, 
which contains the information needed to deal with a memory pixrect. 

linebytes is the number of bytes stored in a row of the primary pixrect This 
is the difference in the addresses between two pixels at the same x-coordinate, 
one row apart. Because a secondary pixrect may not include the full width of its 
primary pixrect, this quantity cannot be computed from the width of the pixrect 
— see Section 3.4. The actual pixels of a memory pixrect are stored someplace 
else in memory, usually an array, which md_image points to; the format of that 
area is described in the next section. The creator of the memory pixrect must 
ensure that md_image contains an even address. md_of f set is the x,y 
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Example 



position of the first pixel of this pixrect in the array of pixels addressed by 
md_image. md_j>rimary is 1 if the pixrect is primary and had its image allo- 
cated dynamically (e.g. by mem_create ( > ). In this case, md_image will 
point to an area not referenced by any other primary pixrect. This flag is interro- 
gated by the pr_destroy ( ) routine: if it is 1 when that routine is called, the 
pixrect’s image memory will be freed. 

The MP DISPLAY bit will be set in md_f lags if the memory pixrect is actually 
a memory mapped frame buffer. The MP_REVERSEVIDEO bit will be set if 
reversevideo is currently in effect for the pixrect (this is only valid if the pixrect 
depth is 1 bit). The MP_386I bit is non-zero if the pixrect image data is in 80386 
format. 

NOTE This flag is ignored on 680X0 based machines. 

The MPJSTATIC is non-zero if the pixrect is static. 

NOTE This flag is ignored on 680X0 based machines. 

md_f lags is present to support memory-mapped display devices like the 
Sim— 2 monochrome video device, and the bit flipping necessary for Sun386i 
machines. See Chapter 2 for details on 80386 format, and the MP_386I and 
MP_STATIC flags. 

Several useful macros are defined in <pixrect /memvar . h>. These macros 
will greatly increase the productivity of the programmer using memory pixrects, 
as well as the reliability of the code. Two commonly used macros are described 
here; see the others in memvar . h. 

To access a memory pixrect’s bitmap and functions, use the mpr_d ( ) macro. It 
generates a pointer to the private data of a memory pixrect: 



♦define mpr_d(pr) ((struct mpr_data *) (pr) ->pr_data) 
) 



The mpr_linebytes macro computes the bytes per line of a primary memory 
pixrect given its width in pixels and the bits per pixel. This includes the padding 
to word bounds. It is useful for incrementing pixel addresses in the y direction, 

or calculating line padding in the bitmap. 


#def ine mpr_linebytes (width, depth) 

( ( (pr_jproduct (width, depth) +15) »3) &~1) 

V* y 



Here is an example program that uses a memory pixrect to do bit manipulations 
on the screen. It opens the frame buffer and copies the bitmap to a memory pix- 
rect of the same size. It then goes through each byte of the memory pixrect, left- 
shifting each byte. Finally, it copies the modified memory pixrect back into the 
screen pixrect. 

Note how the mpr_linebytes macro is used to find the number of bytes used 
to hold a line of the memory pixrect. The mpr_d ( ) macro is also used to sim- 
plify access to the image area of the memory pixrect. 
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Figure 5-1 Example Program using Memory Pixrects 

♦include <pixrect/pixrect_hs . h> 

♦include <stdio.h> 
main () 

{ 

Pixrect *scrn, *mem; 

int ht,wid; 

char *start, *ptr; 

scrn = pr_open ("/dev/fb") ; 

wid = scrn->pr_size . x; 

ht = scrn->pr_size.y; 

mem = mem_c reate (wid, ht, 1) ; 

pr_rop (mem, 0,0, wid, ht, PIX_SRC, scrn, 0,0) ; 

start = (char *) mpr_d (mem) ->md_image ; 

for(ptr = start;ptr < start + mpr_linebytes (wid, 1) * ht;ptr++) *ptr «= 2; 

pr_rop (scrn, 0, 0, wid, ht, PIX_SRC,mem, 0,0) ; 
pr_close (mem) ; 
pr_close (scrn) ; 

} 



5.2. Creating Memory The mem_create ( ) and memjooint ( ) functions allow a client program to 

Pixrects create memory pixrects. 

Create Memory Pixrect Pixrect *mem_create (w, h, depth) 

int w, h, depth; 

A new primary pixrect is created by a call to the procedure mem_create ( ) . w, 
h and depth specify the width and height in pixels, and depth in bits per pixel 
of the new pixrect. Sufficient memory to hold those pixels is allocated and 
cleared to 0, new mpr_data and Pixrect structures are allocated and initial- 
ized, and a pointer to the pixrect is returned. If this can not be done, the return 
value is NULL. On Sun386i systems, the memory pixrects created by 
mem_create () set the MP_I386 flag to 1 (true). 

On 32 bit systems (such as the Sun-3 and Sun-4) the created pixrect will have 
each scan line padded out to a 32 bit boundary, unless it is only 16 bits wide; that 
is, the md_linebytes structure member will contain either 2 or a multiple of 
4. In older Sun releases pixrects created by mem_cre ate () were always pad- 
ded to a 16 bit boundary. 

Create Memory Pixrect from Pixrect *mem__point (width, height, depth, data) 
an Image int width, height, depth; 

short *data; 

The mem point ( ) routine builds a pixrect structure that points to a dynami- 
cally created image in memory. Client programs may use this routine as an alter- 
native to mem create ( ) if the image data is already in memory, width and 
height are the width and height of the new pixrect, in pixels, depth is the 
depth of the new pixrect, in number of bits per pixel, data points to the image 
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to be associated with the pixrecL Unlike the mem_create () routine, the 
mem_point ( ) routine does not set the MP_38 61 flag; the pixrect remains in 
680X0 format. 

Note that mem_j5oint ( ) expects each line of the memory image to be padded 
to a 16 bit boundary. Also, mem_point ( ) does not set the md_primary flag 
so the image will not be automatically freed when the pixrect is destroyed. 

Example Here is an example program which uses a memory pixrect to invert the frame 

buffer contents from top to bottom. It opens the default frame buffer and creates 
a memory pixrect of the same size. It then copies rows of pixels from the frame 
buffer to the memory pixrect in reverse order. Finally, it copies the memory pix- 
rect back to the frame buffer. 



Figure 5-2 Example Program using Memory Pixrects 

♦include <pixrect/pixrect_hs .h> 

main ( ) 

{ 

Pixrect *pr f *tmp; 
int yin, yout; 

if (! (pr = pr_open ("/dev/fb") ) 1 | 

! (tmp = 

mem_create (pr->pr_size .x, pr->pr_size .y, pr->pr_depth) ) ) 
exit (1) ; 

for (yin = 0, yout = pr->pr_size.y - 1; yout >= 0; yin++, yout — ) 
pr_rop(tmp, 0, yout, pr->pr_size .x, 1, PIX_SRC, pr, 0, yin); 

pr_rop (pr, 0, 0, pr->pr_size .x, pr->pr_size .y, PIX_SRC, tmp, 0, 0) ; 

exit (0) ; 



5.3. Static Memory tdefine mpr_static(name, w, h, depth, image) 

Pixrects int w, h, depth; 

short *image; 

A memory pixrect may be created at compile time by using the 
mpr_static() macro, name is a token to identify the generated data objects; 
w, h, and depth are the width and height in pixels, and depth in bits of the pix- 
rect; and image is the address of an even-byte aligned data object that contains 
the pixel values in the format described below, with each line padded to a 16 bit 
boundary. 

If static structures are desired, the macro mpr_static_static should be 
used instead. 
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The macro generates two structures: 




The mpr_data is initialized to point to all of the image data passed in; the 
Pixrect then refers to mem_ops and to name_data. On a Sun386i 
machine, the MP_STATIC flag will be set in the md_flags byte of the pixrect 
data structure; see Chapter 2 for details. Note: Contrary to its name, this macro 
generates structures of storage class extern. 

In memory, the upper-left comer pixel is stored at the lowest address. This 
address must be even. That first pixel is followed by the remaining pixels in the 
top row, left-to-right. Pixels are stored in successive bits without padding or 
alignment. 

Each row of pixels is rounded to at least a 16 bit boundary. For best performance 
on 32 bit systems, pixel rows should be rounded to 32 bit boundaries 
(mem_create does this automatically). However, 16 bit rounding is required for 
static pixrects and mem_point. 

Memory pixrects with depths of 1, 8, 16, 24, and 32 bits are currently supported 
by the pixrect library. If source and destination are both memory pixrects they 
must have an equal number of bits per pixel. 

NOTE If you are running a Sun386i machine. A pixrect’ s image data will be converted 

to 80386 format before being displayed. See Chapter 2 for details. 

Memory pixrects can be used to get data from and send data to the display dev- 
ice. Several routines exist for interfacing Pixwins with memory pixrects. These 
include pw_read ( ) , pw_rop ( ) and pw_wr ite ( ) . Refer to the SunView 1 
Programmer’ s Guide for more details. For applications using the raw device 
without SunView, pr_rop ( ) can be used for operations on memory pixrects. 

Another use of memory pixrects is for processing images that not intended for 
display. User programs can write directly into a pixrect using parameters found 
in the mpr_dat a structure, or they can use mem__point ( ) for a previously 
created image. Memory pixrects can also be written to raster files using the facil- 
ities described in Chapter 6. 
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File I/O Facilities for Pixrects 



Sun Microsystems, Inc. has specified a file format for files containing raster 
images. The format is defined in the header file <rasterfile . h>. Thepix- 
rect library contains routines to perform I/O operations between pixrects and files 
in this raster file format. This I/O is done using the routines of the C Library 
Standard I/O package, requiring the caller to include the header file 
<stdio . h>. 

The raster file format allows multiple types of raster images. Unencoded, and 
run-length encoded formats are supported directly by the pixrect library. Support 
for customer defined formats is implemented by passing raster files with non- 
standard types through filter programs. Sun supplied filters are found in the 
directory /usr/lib/rasf ilters. This directory also includes sample 
source code for a filter that corresponds to one of the standard raster file types to 
facilitate writing new filters. 

6.1. Writing and Reading The sections that follow describe how to store and retrieve an image in a 
Raster Files rasterfile. 

Run Length Encoding The run-length encoding used in raster files is of the form 

<byte><byte> . . .<ESC><0>. . . <byte><ESC><countxbyte> . . . 

where the counts are in the range 0..255 and the actual number of instances of 
<byte> is <count>+l (i.e. actual is 1..256). One- or two-character 
sequences are left unencoded; three -or-morc character sequences are encoded as 
<ESCxcountxbyte>. <ESC> is the character code 128. Each single <ESC> 
in the input data stream is encoded as <ESC><0>, because the <count> in this 
scheme can never be 0 (the actual count can never be 1). <ESC><ESC> is 
encoded as <ESC><1><ESC>. 

This algorithm will fail (make the compressed data bigger than the original data) 
only if the input stream contains an excessive number of one- and two-character 
sequences of the <ESC> character. 
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Write Raster File 



int pr_dump (input_pr, output, colormap, type, copy_flag) 
Pixrect *input_pr; 

FILE *output; 
colormap_t *colormap; 
int type, copy_flag; 

The pr_dump { ) procedure stores the image described by a pixrect onto a file. 
It normally returns 0, but if any error occurs it returns PIX_ERR. The caller can 
write a rectangular sub-region of a pixrect by first creating an appropriate 
input_pr via a call to pr_region ( ) . The output file is specified via out- 
put. The specified output type should either be one of the following standard 
types or correspond to a customer provided filter. 



f 




\ 


#def ine 


RT_OLD 0 




#def ine 


RT_S T AND ARD 1 




#def ine 


RT_BYTE_ENCODED 2 




V 




J 



The RTJSTANDARD type is the common raster file format in the same sense that 
memory pixrects are the common pixrect format: every raster file filter is 
required to read and write this format. The RT_OLD type is very close to the 
RT_STANDARD type; it was the former standard generated by old versions of 
Sun software. The RT_BYTE_ENCODED type implements a run-length encoding 
of bytes of the pixrect image. This usually results in shorter files, although 
pathological images may expand by 50%. 

Specifying any other output type causes pr dump ( ) to pipe a raster file of 
RT_STANDARD type to the filter named convert . type, looking first in direc- 
tories in the user’s $PATH environment variable, and then in the directory 
/usr / lib/rasf ilter s. type is the ASCII corresponding to the specified 
type in decimal. The output of the filter is then copied to output. 

It is strongly recommended that customer-defined formats use a type value of 100 
or more, to avoid conflicts with additions to the set of standard types. The 
RTJEXPERIMENT AL type is reserved for use in the development of experimental 

filters, although it is no longer treated specially. 


♦define RT_EXPERIMENTAL 65535 

s j 



pr_dump ( ) and other functions that start filters wait until the filter process 
exits before returning, so caution is advisable when working with experimental 
filters. 

For pixrects displayed on devices with colormaps, the values of the pixels are not 
sufficient to recreate the displayed image. Thus, the image’s colormap can also 
be specified in the call to pr_dump ( ) . If the colormap is specified as NULL 
but input _pr is a non-monochrome display pixrect, pr_dump ( ) will attempt 
to write the colormap obtained from input_j?r (via pr_getcolormap). The 
following structure is used to specify the colormap associated with input__pr: 
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typedef struct { 




int type; 




int length; 




unsigned char *map[3]; 




} colormap_t; 




v 





The colormap type should be one of the Sun supported types: 

#def ine RMT_NONE 0 
#def ine RMT_EQUAL_RGB 1 
#def ine RMT_RAW 2 

/ 



If the colormap type is RMT_NONE, then the colormap length must be 0. This 
case usually arises when dealing with monochrome displays and 1-bit deep 
memory pixrects. If the colormap type is RMTJEQUAL_RGB, then the map array 
should specify the red (map [ 0 ] ), green (map [ 1 ] ) and blue (map [ 2 ] ) color- 
map values, with each vector in the map array being of the same specified color- 
map length. If the colormap type is RMT_RAW, the first map array (map [ 0 ] ), 
should hold length bytes of colormap data, which will not be interpreted by 
the pixrect library. 

Finally, copy_f lag specifies whether or not input_j>r should be copied to a 
temporary pixrect before the image is output. The copy_f lag value should be 
non-zero if input_pr is a pixrect in a frame buffer that is likely to be asyn- 
chronously modified. The copy flag is also automatically set non-zero for secon- 
dary pixrects, to simplify the code. Note that use of copy_f lag still will not 
guarantee that the correct image will be output unless the pr_rop ( ) to copy 
from the frame buffer is made uninterruptible. 




sun 

microsystems 



Revision A of 9 May 1988 






62 Pixrect Reference Manual 



Figure 6-1 Example Program using pr_dump() 




Read Raster File Pixrect *pr_load( input, colormap) 

FILE * input; 
colormap_t *colormap; 

The pr_load ( ) function can be used to retrieve the image stored in a raster file 
into a pixrect The raster file’s header is read from input, a pixrect of the 
appropriate size is dynamically allocated, the colormap is read and placed in the 
location addressed by colormap, and finally the image is read into the pixrect 
and the pixrect returned. If any problems occurs, pr load ( ) returns NULL. 

As with pr_dump ( ) , if the specified raster file is not of standard type, 
pr_load ( ) first runs the file through the appropriate filter to convert it to 
RT_STANDARD type and then loads the output of the filter. 

Additionally, if colormap is NULL, pr_load ( ) will simply discard any and 
all colormap information contained in the specified input raster file. If color- 
map is non-null pr_load ( ) will load the colormap data even if the type and 
length specified do not match that of the file (see pr_load_colormap ( ) 
below). 



#sun 
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Figure 6-2 Example Program using pr_load ( ) 




6.2. Details of the Raster A handful of additional routines are available in the pixrect library for manipulat- 

File Format ing pieces of raster files. In order to understand what they do, it is necessary to 

understand the exact layout of the raster file format. 

The raster file is in three parts: first, a small header containing eight 32-bit 
int ’s; second, a (possibly empty) set of colormap values; third, the pixel image, 
stored a line at a time, in increasing y order. 

The image is essentially laid out in the file the exact way that it would appear in a 
static memory pixrect. In particular, each line of the image is rounded out to a 
multiple of 16 bits, corresponding to the rounding convention used by static pix- 
rects. 

The header is defined by the following structure: 
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. 

struct rasterfile { 
int ras_magic; 
int ras_width; 
int ras_height; 
int ras_depth; 
int ras_length; 
int ras_type; 
int ras_maptype; 
int ras_maplength; 

} ; 



The ras_magic field always contains the following constant: 



r 


"\ 


#def ine RAS_MAGIC 0x59a66a95 

k. 


J 



The ras_width, ras_height and ras_depth fields contain the image’s 
width and height in pixels, and its depth in bits per pixel, respectively. The depth 
is usually either 1 or 8, corresponding to the standard frame buffer depths. 

The ras_length field contains the length in bytes of the image data. For an 
unencoded image, this number is computable from the ras_width, 
ras_height , and ras_depth fields, but for an encoded image it must be 
explicitly stored in order to be available without decoding the image itself. Note 
that the length of the header and of the possibly empty colormap values are not 
included in the value in the ras_length field; it is only the image data length. 
For historical reasons, files of type RT_OLD will usually have a 0 in the 
ras_length field, and software expecting to encounter such files should be 
prepared to compute the actual image data length if it is needed. The 
ras_maptype and ras_maplength fields contain the type and length in 
bytes of the colormap values, respectively. 

If the ras_maptype is not RMT_NONE and the ras_maplength is not 0, 
then the colormap values are the ras_maplength bytes immediately after the 
header. These values are either uninterpreted bytes (usually with the 
ras_maptype set to RMT_RAW) or the equal length red, green and blue vec- 
tors, in that order (when the ras_maptype is RMT_EQUAL_RGB). In the latter 
case, the ras_maplength must be three times the size in bytes of any one of 
the vectors. 

6.3. W riting Parts of a The following routines are available for writing the various parts of a raster file. 

Raster File Many of these routines are used to implement pr_dump ( ) . First, the raster file 

header and the colormap can be written by calling pr_dump_header ( ) . 

Write Header to Raster File int pr_dump_header (output, rh, colormap) 

FILE *output; 

struct rasterfile *rh; 

colormap_t *colormap; 

pr_dump_header ( ) returns PIX_ERR if there is a problem writing the header 
or the colormap, otherwise it returns 0. If the colormap is NULL, no colormap 
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values are written. 

Initialize Raster File Header Pixrect *pr_dump_init (input_pr, rh, colormap, 

type, copy_flag) 

Pixrect *input_pr; 
struct rasterfile *rh; 
colormap_t *colormap; 
int type, copy_flag; 

For clients that do not want to explicitly initialize the rasterfile struct this routine 
can be used to set up the arguments for pr_dump_header ( ) . The arguments 
to p r_dump_i nit ( ) correspond to the arguments to pr_dump ( ) . However, 
pr_dump_init ( ) returns the pixrect to write, rather than actually writing it, 
and initializes the structure pointed to by rh rather than writing it. If colormap is 
NULL, the ras_maptype and ras_maplength fields of rh will be set to 
RMT_NONE and 0, respectively. 

If any error is detected by pr_dump_init ( ) , the returned pixrect is NULL. If 
there is no error, the copy_f lag is zero, and the input pixrect is suitable for 
direct dumping (a primary memory pixrect), the returned pixrect is simply 
input_pr. However, if copy_f lag is non-zero, or the input pixrect cannot 
be dumped directly, the returned pixrect is dynamically allocated and the caller is 
responsible for deallocating it with pr_destroy ( ) when it is no longer 
needed. 

int pr_dump_image (pr, output, rh) 

Pixrect *pr; 

FILE *output; 
struct rasterfile *rh; 

The actual image data can be output via a call to pr_dump_image ( ) . This 
routine returns 0 unless there is an error, in which case it is PIX_ERR. It cannot 
write the image in a non-standard (filtered) format, since by the time it is called 
the raster file header has already been written. 

Since these routines sequentially advance the output file’s write pointer, 
pr_dump_image ( ) must be called after pr_dump_header ( ) . 

The following routines are available for reading the various parts of a raster file. 
Many of these routines are used to implement pr_load ( ) . Since these rou- 
tines sequentially advance the input file’s read pointer, rather than doing random 
seeks in the input file, they should be called in the order presented below. 



6.4. Reading Parts of a 
Raster File 



Write Image Data to Raster 
File 



Read Header from Raster File int pr_load_header (input, rh) 

FILE * input; 

struct rasterfile *rh; 



The raster file header can be read by calling pr_load_header ( ) . This rou- 
tine reads the header from the specified input, checks it for validity and initializes 
the specified rasterfile structure from the header. The return value is 0 
unless there is an error, in which case it is PIX_ERR. 
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int pr_load_colormap (input, rh, colormap) 

FILE * input; 
struct rasterfile *rh; 
colormap_t * colormap; 

If the header indicates that there is a non-empty set of colormap values, they can 
be read by calling pr_load_colormap ( ) . If the specified colormap is 
NULL, this routine will skip over the colormap values by reading and discarding 
them. If the type and length values in colormap do not match the input file, 
pr_load_colormap ( ) will allocate space for the colormap with malloc, 
read the colormap, and modify colormap before returning. If this occurs, the 
space allocated can be released with a free ( colormap->map [ 0 ] ) . 

The return value is 0 unless there is an error, in which case it is PIX_ERR. 

Read Image from Raster File Pixrect *pr_load_image (input, rh, colormap) 

FILE *input; 

struct rasterfile *rh; 

colormap_t *colormap; 

An image can be read by calling pr_load_image ( ) . If the input is a standard 
raster file type, this routine reads in the image directly. Otherwise, it writes the 
header, colormap, and image into the appropriate filter and then reads the output 
of the filter. In this case, both the rasterfile and the colormap structures will be 
modified as a side-effect of calling this routine. In either case, a pixrect is 
dynamically allocated to contain the image, the image is read into the pixrect, 
and the pixrect is returned as the result of calling the routine. If there is an error, 
the return value is NULL. 

Read Standard Raster File Pixrect *pr_load_std_image (input, rh, colormap) 

FILE * input; 

struct rasterfile *rh; 

colormap_t colormap; 

If it is known that the image is from a standard raster file type, then it can be read 
in by calling pr_load_std_image ( ) . This routine is identical to 
pr_load_image ( ) , except that it will not invoke a filter on non-standard ras- 
ter file types. 



Read Colormap from Raster 
File 
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Writing a Pixrect Driver 



Sun has defined a common programming interface to pixel addressable devices 
that enables, in particular, device independent access to all Sun frame buffers. 
This interface is called the pixrect interface. Existing Sun supported software 
systems access a frame buffer through the pixrect interface. Sun encourages cus- 
tomers with other types of frame buffers (or other types of pixel addressable dev- 
ices) to provide a pixrect interface to these devices. 

This chapter describes how to write a pixrect driver. It is assumed that you have 
already read Chapter 3, Pixrect Operations', it describes the programming inter- 
face to the basic operations that must be provided in order to generate a complete 
pixrect implementation. It is also assumed that you have a copy of Writing Dev- 
ice Drivers The section in that manual on writing the kernel device driver portion 
of the pixrect implementation is important. 

This chapter contains auxiliary material of interest only to pixrect driver imple- 
mentors, not programmers accessing the pixrect interface. This document 
explains how to install a new pixrect driver into the software architecture so that 
it may be used in a device independent manner. Also, utilities and conventions 
that may be of use to the pixrect driver implementor are discussed. 

This chapter walks through the source code for the CG-1 pixrect driver. The 
CG-1 is the Sun-1 color frame buffer. Using this particular driver as an example 
has no significance; another pixrect driver would have worked just as well. 

The actual source code that is presented here is boiler-plate, i.e., almost every 
pixrect driver implementation will be similar. You should be able to make your 
own driver just from the documentation alone. However, a complete source 
example for an existing pixrect driver would probably expedite the development 
of your own driver. The complete device specific source files for the Sun-1 color 
frame buffer pixrect driver is available as a source code purchase option (avail- 
able without a UNIX source license). 

A.l. What You’ll Need These are the tools and pieces that you’ll need before assembling your pixrect 

driver; 

□ You need the correct documentation: 

S unView 1 Programmer’ s Guide 
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A.2. Implementation 
Strategy 



A.3. Files Generated 



SunView 1 System Programmer’ s Guide 
Writing Device Drivers 

□ You need to know how to drive the hardware of your pixel addressable dev- 
ice. At a minimum, a pixel addressable device must have the ability to read 
and write single pixel values. (One could imagine a device that doesn’t even 
meet the minimum requirements being used as a pixel addressable device. 
We will not discuss any of the ways that such a device might fake the 
minimum requirements). 

□ You must have a UNIX kernel building environment. No extra source is 
required. 

□ You must have the current pixrect library file and its accompanying header 
files. No extra source is required. 

This is one possible step-by-step approach to implementing a pixrect driver: 

□ Write and debug pixrect creation and destruction. This involves the pixrect 
kernel device driver that lets you open(2) and mmap(2) the physical device 
from a user process. The private cgl_make routine must be written. The 
cgl_region and cgl_destroy pixrect operation must be written. 

□ Write and debug the basic pixel rectangular region function. The 
cgl_put at tributes and cgl_putcolormap pixrect operations must 
be written in addition to the cgl_rop routine. 

□ Write and debug batchrop routines. The cgl bat chrop pixrect operation 
must be written. 

□ Write and debug vector drawer. The cgl_vector pixrect operation must 
be written. 

□ Write and debug remaining pixrect operations: cgl_stencil, cgl_get, 
cgl_put, cgl_getattributes and cgl_getcolormap. 

□ If the device is to run with SunView, build a kernel with minimal basic pixel 
rectangle function for use by the cursor tracking mechanism in the SunView 
kernel device driver. Also include the colormap access routines for use by 
the colormap segmentation mechanism in the SunView kernel device driver. 

n Load and test SunView programs with new pixrect driver. Experience has 
shown that when you are able to run released SunView programs that your 
pixrect driver is in pretty good shape. 

Here is the list of source files generated that implement the example pixrect 

driver: 

□ cglreg . h - A header file describing the structure of the raster device. It 
contains macros used to address the raw device. 

□ cglvar.h-A header file describing the private data of the pixrect. It con- 
tains external references to pixrect operation of this driver. 
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□ /sys/sundev/cgone . c - The pixrect kernel device driver code. 

□ cgl . c - The pixrect creation and destruction routines. 

□ cgl_region . c - The region creation routine. 

□ pr_makef un . c - Replaces an existing module and contains the vector of 
pixrect make operations. 

□ cgl_batch . c - The batchrop routine. 

□ cgl_colormap . c - The colormap access and attribute setting routines . 

□ cgl_getput . c - The single pixel access routines. 

□ cgl_rop . c - The basic pixel rectangle manipulation routine. 

□ cgl_stencil . c - The stencil routine. 

□ cgl_vec . c - The vector drawer. 

□ cgl_curve . c The curved shape routine. 

□ cgl_j?olyline . c The polyline routine. 

Memory Mapped Devices Some devices are memory mapped; a good example is the bw2, the Sun-2 mono- 

chrome video frame buffer. With such devices, their pixels are manipulated 
directly as main memory; there are no device specific registers through which the 
pixels are accessed. Memory mapped devices are able to rely on the memory 
pixrect driver for many of its operations. The only files that the Sun 2 mono- 
chrome video frame buffer supplies are: 

□ bw2 var . h - A header file describing the private data of the pixrect. It con- 
tains external references to pixrect operation of this driver. 

□ / sy s / sundev/bwtwo . c - The pixrect kernel device driver code. 

□ bw2 . c - The pixrect creation and destruction routines. 



The operations vector for the Sun 2 monochrome pixrect driver is: 




4.4. Pixrect Private Data Each pixrect device must have a private data object that contains instance 

specific data about the state of the driver. It is not acceptable to have global data 
shared among all the pixrects objects. The device specific portion of the pixrect 
data must contain certain information: 

□ An offset from the upper left-hand comer of the pixel device. This offset, 
plus the width and height of the pixrect from the public portion, is used to 
determine the clipping rectangle used during pixrect operations. 
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□ A flag for distinguishing between primary and secondary pixrects. Primary 
pixrects are the owners of dynamically allocated resources shared between 
primary and secondary pixrects. 

□ A file descriptor to the pixrect kernel device. Usually, the file descriptor is 
used while mapping pages into the user process address space so that the 
device may be addressed. One could imagine a pixrect driver that had some 
of its pixrect operations implemented inside the kernel. The file descriptor 
would then be the key to communicating with that portion of the package via 
read(2), write(2) and ioctl(2) system calls. 

Here is other possible data maintained in the pixrect’s private data: 

□ For many devices, a virtual address pointer is part of the private data so that 
the device can be accessed from user code. 

□ For color devices, there is a mask to enable access to specific bit planes. 

□ For monochrome devices, there is a video invert flag. This replaces the 
colormap of color devices. 

A.5. Creation and This section covers the code for pixrect object creation and destruction. Code for 

Destruction the Sun-1 color frame buffer pixrect driver is presented as an example. 

There are two public pathways to creating a pixrect: 

□ pr_open ( ) creates a primary pixrect. 

□ pr_region ( ) creates a secondary pixrect which specifies a subregion in 
an existing pixrect. 

There are two public pathways to destroying a pixrect: 

□ pr_destroy() destroys a primary or secondary pixrect. Clients of the 
pixrect interface are responsible for destroying all extant secondary pixrects 
before destroying the primary pixrect from which they were derived. 

□ pr_close() simply calls pr_destroy () . 

Creating a Primary Pixrect In this section, the private cgl_make pixrect operation is described. This is the 

flow of control for pr_open ( ) : 

□ Higher levels of software call pr_open ( ) , which takes a device file name 
(e.g., / dev/cgoneO). 

□ pr_open ( ) opens the device and finds out its type and size via an FBIOG- 
TYPE ioctl(2) call (see <sun/fbio . h>). 

□ pr_open ( ) uses the type of pixel addressable device to index into the 
pr_makef un array of procedures (more on this later) and calls the refer- 
enced pixrect make function, cgl_make. 

□ cgl_make returns the primary pixrect (it workings are discussed below). 

□ pr_open ( ) closes its handle on the device and the pixrect is returned. 
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Here is a partial listing of cgl . c that contains code that is important to the 
cgl_make procedure. As it is for other code presented in this document, it is 
here so you can refer back to it as you read the subsequent explanation. Some 
lines are numbered for reference and normal C comments have been removed in 
favor of the accompanying text. 




#sun 
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Line cgl.7 does some consistency checking to make sure that the dimensions of 
the pixel addressable device and the client’s idea about the dimensions of the 
device match. 




Line cgl.8 calls the pixrect library routine pr_makef romf d to do most of the 
work: 

□ Allocates a pixrect structure object using the c alloc library call. The 
pixrect is filled in with size and depth parameters. 

□ Allocates an object of the size privdatabytes using the calloc library call 
and placing a pointer to it in the pr_data field of the allocated pixrect. 

□ dup(2)s the passed in file descriptor fd so that when the caller closes the file 
descriptor the device wouldn’t close. 

□ mmap(2) allocates and maps to the device mmapbytes of space. 

□ If an error is detected during any of the above calls, an error is written to the 
standard error output. A NULL pixrect handle is returned in this case. 

□ Returns the allocated pixrect. 

This brings us to the issue of minimizing resources used by the pixrect driver, 
andpr open, cgl_make, can be (and are) called many times thus creating a 
situation in which there are many primary pixrects open at a time. A pixrect 
should maintain an open file descriptor and (usually) a non-trivial amount of vir- 
tual address space mapped into the user process’s address space. Both the 
number of open file descriptors and the virtual address space (maximum 16 
megabytes) are finite resources. However, multiple open pixrects can share all 
these resources. 

The pixrect library supports a resource sharing mechanism, part of which is 
implemented in pr_makef romf d. The devdata parameter passed to 
pr_makef romf d is the head of a linked list of pr_devdata structures of 
which there is one per pixrect driver. It is sufficient to say that through the data 
maintained on this list, sharing of the scarce resources described above can be 
accomplished. 

The curdd parameter passed to pr_makef romf d is set to be the 
pr_devdata structure that applies to the device identified by f d. 

Lines cgl.9 through cgl.14 are concerned with initializing the pixrect’s private 
data with dynamic information described in dd (curdd in the previous para- 
graph) and static information about the pixel addressable device. 
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Line cgl.15 is where the video signal for the device is enabled. By convention, 
every raster device should make sure that it is enabled. 

Creating a Secondary Pixrect In this section, the cgl_region pixrect operation is described. Here is all of 

cgl_region . c. 

> 

struct pixrect *cgl__region (src) 
struct pr_subregion src; 

{ 

register struct pixrect *pr; 

register struct cglpr *scgpr = cgl_d (src .pr) , *cgpr; 
int zero = 0; 

pr__clip (&src, &zero) ; /* cgl_region . 1*/ 

if ( (pr — (struct pixrect *)calloc(l / sizeof (struct pixrect))) == 0) 
return (0) ; /* cgl_region . 2*/ 

if ( (cgpr = (struct cglpr *)calloc(l, sizeof (struct cglpr))) — 0) { 

f ree (pr) ; /* cgl_region . 3*/ 

return (0) ; 

} 

pr->pr__ops = &cgl_ops; /* cgl_region . 4*/ 

pr->pr_size = src. size; /* cgl__region . 5*/ 

pr->pr_depth = CG1_DEPTH; /* cgl_region . 6*/ 

pr->pr_data = (caddr_t ) cgpr; /* cgl_region . 7*/ 

cgpr->cgpr_fd = - 1 ; /* cgl_region . 8*/ 

cgpr->cgpr_va = scgpr->cgpr_va; /* cgl_region . 9*/ 

cgpr->cgpr_planes = scgpr->cgpr_jplanes ; /*cgl_region . 10*/ 

cgpr->cgpr_of f set . x = scgpr->cgpr__of f set .x + src.pos.x; /*cgl_region . 11*/ 
cgpr->cgpr_of f set . y = scgpr->cgpr_of f set . y + src.pos.y; /*cgl_region . 12 */ 
return (pr) ; 

} 

v > 



cgl region is less complex then cgl make. The first thing done is to clip 
the requested subregion to fall within the source pixrect (line cgl region.1). 

pr_clip (dstp, srcp) 

struct pr_subregion *dstp; 
struct pr_jprpos *srcp; 

pr clip adjusts the position and size of dstp, the destination pixrect subre- 
gion, to fall within dstp->pr. If * scrp, the source pixrect position, is not 
zero then the position of the source is clipped to fall within dstp. 

Next, objects are allocated for the pixrect and the pixel addressable device’s 
private data (line cgl _region.2 and eg! _region.3). Then, similarly to the later 
part of cgl_make, the two new data objects are initialized (lines cgl jregion.4 
through cgljregion.I2). One thing to note is that the cgl driver uses a -1 in the 
file descriptor field of the pixrect’s private data to indicate that this pixrect is 
secondary (line cgl region.8). 
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Destroying a Pixrect In this section, the cgl_destroy pixrect operation is described. It works on 

secondary and primary pixrects. Here is more of cgl . c. 

( \ 

cgl_destroy (pr) 

struct pixrect *pr; 

{ 

register struct cglpr *cgpr; 

if (pr — 0) 

return (0 ) ; 

if (cgpr = cgl_d(pr)) { /*cgl.30*/ 

if (cgpr->cgpr_fd != -1) { /*cgl.31*/ 

pr_unmakef romfd (cgpr->cgpr__fd, &cgldevdata) ; /*cgl.32*/ 

} 

free (cgpr) ; /*cgl . 33*/ 

} 

free(pr) ; /*cgl.34*/ 

return (0) ; 

} 

V J 



The pr_makefun() 

Operations Vector 



Note that dynamic memory is freed (lines cgl 33 and cgl 34). Also, note that 
only a primary pixrect (as indicated by a file descriptor that is not -1) invokes a 
call to pr_unmakef romf d (line cgl 32). 

pr_unmakef romfd (fd, devdata) 

struct pr_devdata **devdata; 
int fd; 

This pixrect library routine is the counterpart of pr_makef romf d ( ) . If the 
device identified by the file descriptor f d has no more pixrects associated with it 
(as determined from devdata) then the resources associated with it are 
released. 



As mentioned above, pr open ( ) calls cgl_make ( ) through the 
pr_makef un ( ) procedure vector. This is what pr_makef un ( ) looks like (it 
is the sole contents of pr makef un . c): 



# inc lude <pixrect / pixrect_hs . h> 
tinclude <sun/fbio.h> 

Pixrect * (*pr__makefun [FBTYPE_LASTPLUSONE] ) ( ) = { 
bwl_make , 
cgl_make, 
bw2_make , 
cg2_make f 
gp l__make, 

0 /* bw3_make */ , 

0 /* cg3_make */ , 

0 /* bw4_make */ , 

cg4_make 

} ; 
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pr_makef un ( ) is the routine that pulls in all the code from the different frame 
buffers. If a site is not going to use programs on more than one kind of display, 
the unused slots can be commented out to prevent the code for the unused display 
from being loaded. This has the advantage of reducing disk space usage. How- 
ever, working set size will presumably not be affected due to virtual memory not 
touching unused code. 

For both the case of adding and deleting drivers, loading a compiled version of 
this edited file will have the effect of ignoring the commented out device drivers. 

When adding some new pixrect driver, you need to assign it some unused con- 
stant from <sun/f bio . h>, e.g., FBTYPE_NOTSUNl. This then becomes the 
device identifier for your new pixrect driver. You need to generate a new version 
of the source file prjmakef un . c with the above data structure except that the 
array entry pr_makefun [FBTYPE_NOTSUNl] would contain the pixrect make 
procedure for your FBTYPE_NOTSUNl pixrect driver (line pr_makef un . 1). 
The old pr makef un . o in the pixrect library could be replaced with your new 
pr_makef un . o using ar(l). 

A.6. Pixrect Kernel Device A pixrect kernel device driver supports the pixel addressable device as a com- 
Driver plete UNIX device. It also supports use of this device by the SunView driver so 

that the cursor can be tracked and the colormap loaded within the kernel. The 
document Writing Device Drivers for the Sun Workstation contains the details of 
device driver constmction. It also contains an overview. 

The code in this section comes from cgone.c. In the kernel, suffixes that end 
with a number (like egl) confuse the conventions surrounding device driver 
names. A number suffix refers to the minor device number of a device. There- 
fore, in our example, egl becomes egone where the naming has something to 
do with the pixrect kernel device driver. 

Configurable Device Support Raster devices typically hang off a high speed bus (e.g., Multibus) or are plugged 

into a high speed communications port. At kernel building time the UNIX auto- 
configuration mechanism is told what devices to expect and where they should be 
found. At boot time the auto-configuration mechanism checks to see if each of 
the devices it expects are present. 

This section deals with the auto-configuration aspects of the driver. This driver 
is written in the conventional style that supports multiple units of the same dev- 
ice type. It is recommended that you follow this style even if you aren’t antici- 
pating multiple pixel addressable devices of your type on a single UNIX system. 
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finclude " . . /h/f ile .h" 

#include ” . . /h/uio . h” 

#include " . . /h/ioctl .h" 

#include " . . /machine /mmu . h" 
finclude " . . /machine/pte .h" 
finclude " . . /sun/fbio .h" 
finclude " . ./sundev/mbvar.h" 

#include " . . /pixrect /pixrect . h" 
finclude " . . /pixrect /pr_util . h" 
finclude /pixrect /cglreg .h" 
finclude " . . /pixrect/cglvar .h" 

fif NWIN > 0 

f define CG1_0PS &cgl_ops 
struct pixrectops cgl_ops = { 
cgl_rop, 

cgl_putcolormap, 
cgl_put attributes, 

} ; 

felse 

fdefine CG1_0PS (struct pixrectops *)0 
fendif 

fdefine CG1SIZE (sizeof (struct cglfb) ) 
struct cglpr cgoneprdatadef ault == 

{ 0, 0, 255, 0, 0 } ; 
struct pixrect cgonepixrectdef ault = 

{ CG1_0PS, { CG1_WIDTH, CG1_HEIGHT }, CG1__DEPTH, /* filled in later */ 0 } ; 



/* 

* Driver information for auto-configuration stuff. 

*/ 

int cgoneprobe ( ) , cgoneint r ( ) ; 
struct pixrect cgonepixrect [NCGONE] ; 
struct cglpr cgoneprdat a [NCGONE] ; 
struct mb_device *cgoneinfo [NCGONE] ; 
struct mb_driver cgonedriver = { 

cgoneprobe, 0, 0, 0, 0, cgoneint r, 

CG1SIZE, "cgone", cgoneinfo, 0, 0, 0, 

} ; 

/* 

* Only allow opens for writing or reading and writing 

* because reading is nonsensical. 

*/ 

cgoneopen (dev, flag) 
dev__t dev; 

{ 

return (fbopen (dev, flag, NCGONE, cgoneinfo)); 

} 

/* 
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* When close driver destroy pixrect. 

*/ 

/*ARGSUSED*/ 
cgoneclose(dev, flag) 
dev_t dev; 

{ 

register int unit — minor (dev); 

if ( (caddr_t ) &cgoneprdata [unit ] == cgonepixrect [unit ] .pr__data) { 
bzero ( (caddr_t ) Scgoneprdata [unit ] , sizeof (struct cglpr) ) ; 
bzero ( (caddr_t ) &cgonepixrect [unit ] , sizeof (struct pixrect)) 

} 

} 

/*ARGSUSED*/ 

cgoneioctl (dev, cmd, data, flag) 
dev_t dev; 
caddr_t data; 

{ 

register int unit = minor (dev); 
switch (cmd) { 
case FBIOGTYPE : { 

register struct fbtype *fb = (struct fbtype *)data; 

fb->fb_type = FBTYPE__SUN1C0L0R; 
fb->fb_height = 480; 
fb->fb_width = 640; 
f b->fb_depth =8; 
fb->fb_cmsize = 256; 
fb->fb_size = 512*640; 
break; 

} 

case FBIOGPIXRECT : { 

register struct fbpixrect *fbpr = (struct fbpixrect *)data; 
register struct cglfb *cglfb = 

(struct cglfb *) cgoneinf o [ (unit ) ] ->md_addr; 

/* 

* "Allocate" and initialize pixrect data with default. 

*/ 

fbpr->fbpr_jpixrect = &cgonepixrect [unit ] ; 
cgonepixrect [unit ] = cgonepixrectdefault ; 

fbpr->fbpr_pixrect->pr__data = (caddr__t) &cgoneprdata [unit ] ; 
cgoneprdata [unit] = cgoneprdatadef ault ; 

/* 

* Fixup pixrect data. 

*/ 

cgoneprdata [unit ] ,cgpr_va = cglfb; 

/* 

* Enable video 
*/ 
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cgl_setreg (cglfb, CG_FUNCREG , CG_VIDEOENABLE) ; 

/* 

* Clear interrupt 
*/ 

cgl_intclear (cglfb) ; 
break; 

} 

default : 

return (ENOTTY) ; 

} 

return (0) ; 

> 

/* 

* We need to handle vertical retrace interrupts here. 

* The color map(s) can only be loaded during vertical 

* retrace; we should put in ioctls for this to synchronize 

* with the interrupts. 

* FOR NOW, see comments in the code . 

*/ 

cgoneintclear (cglfb) 

struct cglfb *cglfb; 

{ 

/* 

* The Sun-1 color frame buffer doesn't indicate that an 

* interrupt is pending on itself so we don't know if the interrupt 

* is for our device. So, just turn off interrupts on the cgone board. 

* This routine can be called from any level. 

*/ 

cgl_intclear (cglfb) ; 

/* ~ 

* We return 0 so that if the interrupt is for some other device 

* then that device will have a chance at it. 

*/ 

return (0 ) ; 

} 

int 

cgoneintr ( ) 

{ 

return (fbintr (NCGONE, cgoneinfo, cgoneintclear)); 

} 

/ *ARGSUSED* / 

cgonemmap (dev, off, prot) 
dev_t dev; 
off_t off; 
int prot; 

{ 

return (fbmmap (dev, off, prot, NCGONE, cgoneinfo, CG1SIZE) ) ; 

1 
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#include " . . /sundev/cgreg.h" 

/* 

* Note: using old cgreg.h to peek and poke for now. 

*/ 

/* 

* We determine that the thing we're addressing is a color 

* board by setting it up to invert the bits we write and then writing 

* and reading back DATA1, making sure to deal with FIFOs going and coming. 
*/ 

#def ine DATA1 0x5C 
#define DATA2 0x33 
/*ARGSUSED*/ 
cgoneprobe (reg f unit) 
caddr_t reg; 
int unit; 

{ 

register caddr_t CGXBase; 
register u_char *xaddr f *yaddr; 

CGXBase = reg; 

if (pokec ( (caddr_t) GR_f reg, GR_copy_invert) ) 
return (0) ; 

if (pokec ( (caddr_t) GR__mask, 0)) 
return (0) ; 

xaddr = (u_char *) (CGXBase + GR_x_select + GR_update + GR_setO) ; 
yaddr = (u_char *) (CGXBase + GR_y_select + GR_setO) ; 
if (pokec ( (caddr_t) yaddr , 0) ) 
return (0) ; 

if (pokec ( (caddr_t) xaddr , DATA1) ) 
return (0) ; 

(void) peekc ( (caddr_t) xaddr) ; 

(void) pokec ( (caddr__t) xaddr , DATA2 ) ; 

if (peekc ( (caddr_t) xaddr) == ('DATA1 & OxFF) ) { 

/* 

* The Sun-1 color frame buffer doesn't indicate that an 

* interrupt is pending on itself. 

* Also, the interrupt level is user program changable . 

* Thus, the kernel never knows what level to expect an 

* interrupt on this device and doesn't know is an interrupt 

* is pending. 

* So, we add the cgoneintr routine to a list of interrupt 

* handlers that are called if no one handles an interrupt. 

* Add_def ault_intr screens out multiple calls with the same 

* interrupt procedure . 

*/ 

add_def ault_intr (cgoneintr) ; 
return (CG1SIZE) ; 

) 

return (0) ; 



#endif 
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This is how the driver is plugged into the auto-configuration mechanism, 
/etc/conf ig reads a line in the configuration file for a Sun-1 color frame 
buffer: 



device 



cgoneO at mbO csr OxecOOO priority 3 



An external reference to cgonedr iver (line cgone.4 ) is made in a table main- 
tained by the auto-configuration mechanism. At boot time, if the auto- 
configuration mechanism can resolve the reference to cgonedriver then the 
contents of this structure are used to configure in the device: 

□ cgoneprobe - The name of the probe procedure (line cgone.5). 

□ cgoneintr - The name of the interrupt procedure (line cgone.6). 

□ CG1SIZE - The size in bytes of the address space of the device. 

□ cgone - The prefix of the device. Used in status and error messages. 

□ cgoneinf o - The array of devices pointers of the driver’s type (line 

cgone. 2). 

□ The other field’s defaults suffice for most pixel addressable devices. 

cgoneprobe is called to let the driver decide if the virtual address at reg is 
indeed a device that this driver recognizes as one of its own. The unit argu- 
ment is the minor device number of this device. Writing a good probe routine 
can be difficult. The trick is to use some idiosyncrasy of the device that differen- 
tiates it from others. The real driver for the Sun-1 color frame buffer determines 
that it is addressing a Sun-1 color frame buffer by setting it up to invert the data 
written to it and reading back the result. The details of this code are not impor- 
tant to this discussion and is not included. Zero is returned if the probe fails and 
CG1SIZE is returned if the probe succeeds. 

cgoneintr is called when an interrupt is generated at the beginning of the 
vertical retrace. There are a variety of things that one might want to synchronize 
with such an interrupt, e.g., load the colormap or move the cursor. Currently, the 
utility f bintr simply disables the interrupt from happening again (line 
cgone.6). 

int fbintr (numdevs, mb_devs, intclear) 
int numdevs ; 

struct mb_device **mb_devs; 
int (*intclear) () ; 

numdevs is the maximum number of devices of these type configured. 
mb_devs is the array of devices descriptions, intclear is called back to 
actually turn off the interrupt for a particular device, intclear must have the 
same calling sequence as cgoneintclear (line cgone.7), i.e., it take the vir- 
tual address of the device to disable interrupts. cgl_int clear (line cgone.8) 
is a macro that actually disables the interrupts of cglfb. 
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Open When an open system call is made at the user level cgoneopen ( ) is called. 




cgoneopen ( ) uses the utility f bopen ( ) . 

int fbopen(dev, flag, numdevs, mb_devs) 
dev_t dev; 

int flag, numdevs; 

struct mb_devd.ce **mb_devs; 

f bopen ( ) checks to see if dev is available for opening. If not the error ENXIO 
is returned. If flag doesn’t ask for write position (FWRITE) then the error EIN- 
VAL is returned. Normally, zero is returned on a successful open. 

Mmap The memory map routine in a device driver is responsible for returning a single 

physical page number of a portion of a device. 




cgonemmap ( ) used the utility f bitmap ( > . 

int fbmmap(dev, off, prot, numdevs, mb_devs, size) 
dev_t dev; 
off__t off; 

int prot, numdevs, size; 

struct mb_device **mb_devs; 

The parameters to f bitmap ( ) are similar to f bopen ( ) . However, of f is the 
offset in bytes from the beginning of the device, prot is passed through but 
currently not used. 
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Ioctl A pixrect kernel device driver must respond to two input/output control requests: 

□ FBIOGTYPE — Describe the characteristics of the pixel addressable device. 

□ FBIOGPIXRECT — Hand out a pixrect that may be used in the kernel. This 
ioctl call is made from within the kernel. This is only required of frame 
buffers. 

/ 

♦if NWIN >0 /* cgone.9*/ 

♦define CGl_OPS &cgl_ops 
struct pixrectops cgl__ops = { 
cgl_rop, /*cgone.l0*/ 

cgl_j?utcolormap, 

} ; 

♦else 

♦define CGl__OPS (struct pixrectops *) 0 
♦endif 

struct cglpr cgoneprdatadef ault = 

{ 0, 0, 255 , 0, 0 } ; 
struct pixrect cgonepixrectdef ault = 

{ CGl_OPS, { CG1_WIDTH, CG1_HEIGHT }, CG1_DEPTH, /* filled in later */ 0 } ; 

struct pixrect cgonepixrect [NCGONE] ; /*cgone.ll*/ 
struct cglpr cgoneprdata [NCGONE] ; 

cgoneioctl (dev, cmd, data, flag) 
dev__t dev; 
c a ddr_t da t a ; 

{ 

register int unit = minor (dev); 

switch (cmd) { 
case FBIOGTYPE: { 

register struct fbtype *fb = (struct fbtype *)data; 

fb->fb_type = FBTYPE_SUNlCOLOR; 

fb->f b__height = CG1_HEIGHT; 

fb->fb_width = CG1_WIDTH; 

f b->f b_depth = 8; 

fb->fb_cmsize = 256; 

fb~>fb__size = CG1_HEIGHT*CG1_WIDTH; 
break; 

} 

case FBIOGPIXRECT: { 

register struct fbpixrect *fbpr = (struct fbpixrect *)data; 
register struct cglfb *cglfb = 

(struct cglfb *) cgoneinfo [ (unit) ] ->md_addr; 
fbpr->fbpr_pixrect = &cgonepixrect [unit ] ; /*cgone.l2*/ 

cgonepixrect [unit] = cgonepixrectdef ault ; /*cgone.l3*/ 

fbpr->fbpr_pixrect->pr_data = (caddr_t) &cgoneprdata [unit ] ; /*cgone . 14*/ 
cgoneprdata [unit] = cgoneprdatadef ault ; /*cgone . 15*/ 
cgoneprdata [unit ] . cgpr_va = cglfb; /*cgone.l6*/ 

cgl__setreg (cglfb, CG_FUNCREG, CG_VIDEOENABLE) ; /*cgone.l7*/ 
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cgl_intclear (cglfb) ; /*cgone.l8*/ 
break; 

} 

default ; 

return (ENOTTY) ; 

} 

return (0) ; 

} 

j 



The SunView driver isn’t configured into the system when NWIN = 0 (line 
cgone.9 ). When there is no SunView driver, don’t reference the pixrect opera- 
tions cgl_rop ( ) and cgl_putcolormap () . The kernel version of 
cgl_rop ( ) (line cgone.10 ) only needs to be able to read and write memory 

pixrects for cursor management. Thus, you can 
— 

#if ndef KERNEL 

/* code not associated with reading and writing */ 

/* memory pixrects */ 
fendif KERNEL 

^ > 



to reduce the size of the code. 

Memory for pixrect public (pixrect structure) and private (cglpr structure) 
objects is provided by arrays of each (line cgone.ll) NCGONE long. A device n 
in these correspond to device n in cgoneinf o. 

Lines cgone.12 through cgone.16 initialize a pixrect for a particular device. This 
ioctl call should enable video for a frame buffer (line c gone. 17) and disable 
interrupts as well (line cgone.18). 

Close When the device is no longer being referenced, cgoneclose ( ) is called. All 

that is done is that the pixrect data structures of the device are zeroed. 

- - — 

cgoneclose (dev, flag) 
dev_t dev; 

{ 

register int unit = minor (dev) ; 

if ( (caddr_t) Scgoneprdata [unit] == cgonepixrect [unit] .pr_data) { 
bzero ( (caddr_t) Scgoneprdata [unit] , sizeof (struct cglpr) ) ; 
bzero ( (caddr_t) Scgonepixrect [unit] , sizeof (struct pixrect)); 

} 

} 

#endif 
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Plugging Your Driver into 
UNIX 



A.7. Access Utilities 



You need to add the device driver procedures to cdevsw in 

/sys/sun/conf . c after assigning a new major device number to your driver: 


#include "cgone. h" 

#if NCGONE > 0 

int cgoneopen(), cgonemmap (), cgoneioctl ( ) ; 
int cgoneclose () ; 

#else 

fdefine cgoneopen nodev 
#define cgonemmap nodev 
#define cgoneioctl nodev 
fdefine cgoneclose nodev 
fendif 

t 

cgoneopen, cgoneclose, nodev, nodev, /*14*/ 
cgoneioctl, nodev, nodev, 0, 
seltrue, cgonemmap, 

1 , 

v > 



Also, you need to add the new files associated with your driver to 
/ sys/ conf /files . sun: 

\ 

pixrect /cgl__colormap . c optional cgone win device-driver 
pixrect / eg l_r op . c optional cgone win device-driver 
sundev/ cgone . c optional cgone device-driver 
v > 



This section describes utilities used by pixrect drivers. The pixrect header files 
memvar . h, pixrect . h and pr_ut il . h contain useful macros that you 
should familiarize yourself with; they are not documented here. 

pr_clip (dstp, srep) 

struct pr_subregion *dstp; 
struct pr_jprpos *srcp; 

pr__clip adjusts the position and size of dstp, the destination pixrect subre- 
gion, to fall within dstp->pr . If * serp, the source pixrect position, is not 
zero then the position of the source is clipped to fall within dstp. 

Two operations on operations, pr_reversesrc ( ) and pr_reversedst ( ) , 
are provided for adjusting the operation code to take into account video reversing 
of monochrome pixrects of either the source or the destination. 
r ■> 

char pr_reversedst [16] ; 

char pr_reversesrc [16] ; 

V / 



These are implemented by table lookup in which the index into the tables is 
(op»l ) & OxF where op is the operation passed into pixrect public procedures. 
This process can be iterated, e.g.. 
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A.8. Rop 



A.9. Batchrop 



A. 10. Vector 



Importance of Proper 
Clipping 



A. 11. Colormap 
Monochrome 



A. 12. Attributes 



pr_reversedst [pr_reversesrc [op] ]. 

These are the major cases to be considered with the pwo_rop ( ) operation: 

□ Case 1 — we are the source for the pixel rectangle operation, but not the des- 
tination. This is a pixel rectangle operation from the frame buffer to another 
kind of pixrect. If the destination is not memory, then we will go indirect by 
allocating a memory temporary, and then asking the destination to operate 
from there into itself. 

□ Case 2 — writing to your frame buffer. This consists of 4 different cases 
depending on where the data is coming from: from nothing, from memory, 
from some other pixrect, and from the frame buffer itself. When the source 
is some other pixrect, other than memory, ask the other pixrect to read itself 
into temporary memory to make the problem easier. 

A simple batchrop implementation could iterate on the batch items and call rop 
for each. Even in a more sophisticated implementation, while iterating on the 
batch items, you might also choose to bail out by calling rop when the source is 
skewed, or if clipping causes you to chop off in left-x direction. 

There are some notable special cases that you should consider when drawing vec- 
tors: 

□ Handle length 1 or 2 vectors by just drawing endpoints, 
a If vector is horizontal, use fast algorithm. 

□ If vector is vertical, use fast algorithm. 

The hard part in vector drawing is clipping, which is done against the rectangle 
of the destination quickly and with proper interpolation so that the j aggies in the 
vectors are independent of clipping. 

Each color raster device has its own way of setting and getting the colormap. 

For monochrome raster devices, when pr_put colormap ( ) is called, the con- 
vention is that if red [ 0 ] is zero then the display is light on dark, otherwise dark 
on light. For monochrome raster devices, when pr_get colormap ( ) is 
called, the convention is that if the display is light on dark then zero is stored in 
red [ 0 ] , green [ 0 ] and blue [ 0 ] and -1 is stored in other positions in the 
color map. Otherwise, if the display is dark on light, then zero and -1 are 
reversed. 

pr_getattributes ( ) and pr_put at tributes ( ) operations get or set a 
bitplane mask in color pixrects, respectively. 
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Monochrome 

A. 13. Pixel 
A. 14. Stencil 



A. 15. Polygon 



Monochrome devices ignore pr_putattribute ( ) calls that are setting the 
bitplane mask. Monochrome devices always return 1 when 
pr_get attribute ( ) asking for the bitplane mask. 

pwo_get ( ) and pwo_put ( ) operations get or set a single pixel, respectively. 

In its most efficient implementation, stencil code parallels rop code, all the while 
considering the 2 dimensional stencil. One way to implement stencil is to use 
rops. We pay a small efficiency penalty for this. You may not consider writing 
the special purpose code worthwhile for the bitmap stencils since they probably 
won’t get used nearly as much as rop. Here’s the basic idea (Temp is a tem- 
porary memory pixrect): 



— 
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pr_polyline ( ) is a natural extension to pr_vect or () . It is especially 
useful for devices that can optimize this operation. 
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Pixrect Functions and Macros 



B.l. Making Pixrects 



T able B - 1 Pixrects 



Name 


Function 


Create Pixrect 


Pixrect *pr open (devicename) 
char *devicename; 


Create Secondary 
Pixrect 


#define Pixrect *pr_region (pr , x, y, w, h) 
Pixrect *pr; 
int x, y, w, h; 


Release Pixrect 
Resources 


#define pr__close (pr ) 
Pixrect *pr; 


Release Pixrect 
Resources 


#define pr destroy (pr) 
Pixrect *pr; 


Subregion Create 
Secondary Pixrect 


#define Pixrect *prs_region ( subreg) 
struct pr_subregion subreg; 


Subregion Release 
Pixrect Resources 


fdefine prs_destroy (pr ) 
Pixrect *pr; 


Convert 680X0 pixrect 
to 386i pixrect 


void pr__flip(pr) 
Pixrect *pr; 
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B.2. Text 



Table B-2 Text 



Name 


Function 


Compute Bounding Box 
of Text String 


pf_textbound (bound, len, font, text) 
struct pr subregion *bound; 
int len; 

Pixfont *font; 
char *text; 


Compute Location of 
Characters in Text 
String 


struct pr size pf textbatch (where, lengthp, font, text) 
struct pr_pos where []; 
int * lengthp; 

Pixfont *font; 
char *text; 


Compute Width and 
Height of Text String 


struct pr size pf textwidth (len, font, text) 
int len; 

Pixfont *font; 
char *text; 


Load Font 


Pixfont *pf_open (name) 
char *name; 


Load Private Copy of 
Font 


Pixfont *pf_open_private (name) 
char *name; 


Load System Default 
Font 


Pixfont *pf_def ault ( ) 


Release Pixfont 
Resources 


pf_close (pf ) 
Pixfont *pf; 


Unstructured Text 


pr_text(pr, x, y, op, font, text) 
Pixrect *pr; 
int x, y, op; 

Pixfont *font; 
char *text; 




pr_ttext(pr, x, y, op, font, text) 
Pixrect *pr; 
int x, y, op; 

Pixfont *font; 
char *text; 


Write Text and 
Background 


pf_t ext (where, op, font, text) 
struct pr^prpos where; 
int op; 

Pixfont *font; 
char *text; 
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Table B-2 Text — Continued 



Name 


Function 


Write Text 


pf_t text (where, op, font, text) 




struct pr_jprpos where; 




int op; 




Pixfont *font; 




char *text; 
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B.3. Raster Files 



Table B-3 Raster Files 



Name 


Function 


Initialize Raster File 
Header 


Pixrect *pr dump init (input pr, rh, colormap, type, 
copy_f lag) 

Pixrect *input_pr; 
struct rasterfile *rh; 
colormap_t * colormap; 
int type, copy_flag; 


Read Colormap from 
Raster File 


int pr_load_colormap (input , rh, colormap) 

FILE *input; 

struct rasterfile *rh; 

colormap t * colormap; 


Read Header from 
Raster File 


int pr_load__header (input, rh) 

FILE *input; 

struct rasterfile *rh; 


Read Image from Raster 
File 


Pixrect *pr_load_image (input , rh, colormap) 
FILE *input; 
struct rasterfile *rh; 
co lormap_t * co lormap ; 


Read Raster File 


Pixrect *pr__load( input, colormap) 
FILE *input; 
colormap_t * colormap ; 


Read Standard Raster 
File 


Pixrect *pr_load_std_image (input , rh, colormap) 

FILE *input; 

struct rasterfile *rh; 

colormap_t colormap; 


Write Header to Raster 
File 


int pr_dump__header (output , rh, colormap) 
FILE ^output; 
struct rasterfile *rh; 
c o 1 o r map_t * c o 1 o r map ; 


Write Image Data to 
Raster File 


int pr_dump_image (pr , output, rh) 
Pixrect *pr; 

FILE ^output; 

struct rasterfile *rh; 


Write Raster File 


int pr_dump (input_pr , output, colormap, type, copy_flag) 
Pixrect *input_pr ; 

FILE ^output; 
c o 1 o r map_t * c o 1 o r map ; 
int type, copy_flag; 
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B.4. Memory Pixrects 



T able B -4 Memory Pixrects 



Name 


Function 


Create Memory Pixrect 
from an Image 


Pixrect *mem__point (width, height, depth, data) 
int width, height, depth; 
short *data; 


Create Memory Pixrect 


Pixrect *mem_create (w, h, depth) 
int w, h, depth; 


Create Static Memory 
Pixrect 


♦define mpr_static(name, w, h, depth, image) 
int w, h, depth; 
short * image; 


Get Memory Pixrect 
Data Bytes per Line 


♦define mpr_linebytes (width, depth) 

( ( (pr_product (width, depth) +15) »3) 1) 


Get Pointer to Memory 
Pixrect Data 


♦define mpr_d(pr) 

((struct mpr_data *) (pr) ->pr__data) 



Variations for the Sun386i: 

□ mem_point ( ) on the Sun386i does not flip the bitmap pointed to by *data. The pixrect structure returned 
does not have the MP _STATIC or the MP_1 38 6 flag set. 

□ mem_creat e ( ) on the Sun386i creates an empty pixrect with the MP I38 6 flag set. 

□ mpr_static ( ) on the Sun386i creates a pixrect with both the MP_I386 and MP_STATIC flags set. 
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B.5. Colormaps and Bitplanes 



Table B-5 Colormaps and Bitplanes 



Name 


Function 


Exchange Foreground 
and Background Colors 


pr__reversevideo (pr , min, max) 
Pixrect *pr; 
int min, max; 


Get Colormap Entries 


♦define p r_get colormap (pr, index, count, red, green, 
blue) 

Pixrect *pr; 
int index, count; 

unsigned char red[], green [], blue[]; 


Get Plane Mask 


♦define pr_getattributes (pr , planes) 
Pixrect *pr; 
int *planes; 


Set Background and 
Foreground Colors 


pr_blackonwhite (pr, min, max) 
Pixrect *pr; 
int min, max; 


Set Colormap Entries 


♦define pr_jputcolormap (pr, index, count, red, green, 
blue) 

Pixrect *pr; 
int index, count; 

unsigned char red[], green [], bluet]; 


Set Foreground and 
Background Colors 


pr_whiteonblack (pr , min, max) 
Pixrect *pr; 
int min, max; 


Set Plane Mask 


♦ define pr_j?utattributes (pr , planes) 
Pixrect *pr; 
int *planes; 


Subregion Get 
Colormap Entries 


♦ define prs__get colormap (pr, index, count, red, green, 
blue) 

Pixrect *pr; 
int index, count; 

unsigned char red[], green [], bluet]; 


Subregion Get Plane 
Mask 


♦define prs_getattributes (pr , planes) 
Pixrect *pr; 
int *planes; 


Subregion Set 
Colormap Entries 


♦define prs_put colormap (pr , index, count, red, green, 
blue) 

Pixrect *pr; 
int index, count; 

unsigned char red[], green [], bluet]; 
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Table B-5 Colormaps and Bitp lanes — Continued 



Name 


Function 


Subregion Set Plane 
Mask 


tdefine prs putattributes (pr, planes) 
Pixrect *pr; 
int *planes; 
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B.6. Rasterops 



Table B-6 Rasterops 



Name 


Function 


Draw Textured or Solid 
Lines with Width 


tdefine pr_line(pr, xO, yO f xl, yl, brush, tex, op) 

Pixrect *p£; 

int xO, yO, xl, yl; 

struct pr brush *brush; 

struct pr_texture *tex; 

int op; 


Draw Textured Polygon 


pr_polygon_2 (dpr, dx, dy, nbnds, npts, vlist, op, 
spr, sx, sy) 

Pixrect *dpr, *spr; 
int dx, dy 
int nbnds , npt s [ ] ; 
struct pr_pos *vlist; 
int op, sx, sy; 


Draw Vector 


fdefine pr_vector (pr, xO, yO, xl, yl, op, value) 
Pixrect *pr; 

int xO, yO, xl, yl, op, value; 


Get Pixel Value 


tdefine pr_get(pr, x, y) 
Pixrect *pr; 
int x, y; 


Masked Raster Op 


tdefine pr_stencil (dpr , dx, dy, dw, dh, op, 
stpr, stx, sty, spr, sx, sy) 

Pixrect *dpr, *stpr, *spr; 

int dx, dy, dw, dh, op, stx, sty, sx, sy; 


Multiple RasterOp 


tdefine pr_batchrop (dpr , dx, dy, op, items, n) 

Pixrect *dpr; 

int dx, dy, op, n; 

struct pr_prpos items []; 


RasterOp 


tdefine pr_rop(dpr, dx, dy, dw, dh, op, spr, sx, sy) 

Pixrect *dpr, *spr; 

int dx, dy, dw, dh, op, sx, sy; 


Replicated Source 
RasterOp 


pr_replrop (dpr, dx, dy, dw, dh, op, spr, sx, sy) 

Pixrect *dpr, *spr; 

int dx, dy, dw, dh, op, sx, sy; 


Set Pixel Value 


tdefine pr_put(pr, x, y, value) 
Pixrect *pr; 
int x, y, value; 
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Table B-6 Rasterops — Continued 



Name 


Function 


Subregion Draw Vector 


♦define prs_vector (pr , posO, posl, op, value) 
Pixrect *pr; 

struct pr_pos posO, posl; 
int op, value; 


Subregion Get Pixel 
Value 


#define prs_get (srcprpos) 
struct pr_prpos srcprpos; 


Subregion Masked 
RasterOp 


#define prs_stencil (dstregion, op, stenprpos, srcprpos) 
struct pr_subregion dstregion; 
int op; 

struct pr_prpos stenprpos, srcprpos; 


Subregion Multiple 
RasterOp 


#define prs__batchrop (dstpos, op, items, n) 
struct pr_jprpos dstpos; 
int op, n; 

struct pr_prpos items [] ; 


Subregion RasterOp 


♦define prs rop (dstregion, op, srcprpos) 
struct pr_subregion dstregion; 
int op; 

struct pr__prpos srcprpos; 


Subregion Replicated 
Source RasterOp 


♦define prs__replrop (dsubreg, op, sprpos) 
struct pr_subregion dsubreg; 
struct prjprpos sprpos; 


Subregion Set Pixel 
Value 


♦define prs_put (dstprpos, value) 
struct pr_prpos dstprpos; 
int value; 


Trapezon RasterOp 


pr_traprop (dpr , dx, dy, t, op, spr, sx, sy) 

Pixrect *dpr, *spr; 

struct pr_trap t; 

int dx, dy, sx, sy op; 
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B.7. Double Buffering 



Table B-7 Double Buffering 



Name 


Function 


Get Double Buffering 


pr_dbl_get (pr, attribute) 


Attributes 


Pixrect *pr; 




int attribute; 


Set Double Buffering 


pr_dbl_set (pr, attribute_list ) 


Attributes 


Pixrect *pr; 




int *attribute_list ; 
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Pixrect Data Structures 



T able C- 1 Pixrect Data Structures 



Brush 



Name 



Data Structure 



typedef struct pr__brush { 
int width; 

} Pr brush; 



Character Descriptor struct pixchar { 

struct pixrect *pc_j?r; 
struct pr_jpos pc_home; 
struct pr_jpos pc_adv; 



Font Descriptor typedef struct pixfont { 

struct pr_size pf_def aultsize; 
struct pixchar pf__char [256] ; 

} Pixfont; 



Pixrect typedef struct pixrect { 

struct pixrectops *pr_ops; 
struct pr_size pr_size; 
int pr_depth; 
caddr_t pr_data; 

} Pixrect; 
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Table C- 1 Pixrect Data Structures — Continued 



Name 



Pixrect Operations 



Data Structure 



struct pixrectops { 
int (*pro_rop) () ; 
int (*pro_stencil) (); 
int (*pro_batchrop) (); 
int (*pro_nop) () ; 
int (*pro_destroy) (); 
int (*pro_get) () ; 
int (*pro_put) () ; 
int (*pro__vector ) Ob- 
struct pixrect * ( *pro_region) () ; 
int (*pro_putcolormap) (); 
int (*pro__getcolormap) (); 
int (*pro_j?utattributes) () ; 
int <*pro_getattributes) () ; 



Position 



Position Within a 
Pixrect 



struct pr_pos { 
int x f y; 

In- 
struct pr^prpos { 

struct pixrect *pr; 
struct pr_pos pos; 
In- 
struct pr_size { 
int x, y; 



Subregion 



struct pr_subregion { 
struct pixrect *pr; 
struct pr_pos pos; 
struct pr_size size; 
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Name 



Data Structure 

Texture typedef struct pr_texture { 

short ^pattern; 
short offset; 

struct pr_texture_options { 
unsigned startpoint : 1, 
endpoint : 1, 
balanced : 1, 
givenpattern : 1 , 
res_fat : 1, 
res_poly: 1, 
res_mvlist : 1, 
res_right : 1, 

r e s c lose : 1; 

} options; 
short res_polyof f ; 
s ho r t re s__o 1 dpat In ; 
short res_fatoff; 

} Pr_texture; 

Trapezon struct pr_trap { 

struct pr_fall *left, *right; 
int yO f yl; 

}; 

Trapezon Chain struct pr_chain { 

struct pr_chain *next; 
struct pr__size size; 
int *bits; 

}; 

Trapezon Fall struct pr_fall { 

struct pr_pos pos; 
struct pr_chain *chain; 

} ; 
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D 



Curved Shapes 



This appendix describes pr_traprop ( ) , a function for rendering curved 
shapes with Pixrect. pr_traprop() is an advanced pixrect operation analo- 
gous to pr_rop ( ) . 

The curve to be rendered must first be stored in a data structure called pr_trap 
which is based on a region called a trapezon, rather than on a rectangle. A tra- 
pezon is a region with an irregular boundary. Like a rectangle, a trapezon has 
four sides: top, bottom, left, and right. The top and bottom sides of a trapezon 
are straight and horizontal. A trapezon differs from a rectangle in that its left and 
right sides are irregular curves, called falls, rather than straight lines. 

A fall is a line of irregular shape. Vertically, a fall may only move downward. 
Horizontally, a fall may move to the left or to the right, and this horizontal 
motion may reverse itself. A fall may also sustain pure horizontal motion, that 
is, horizontal motion with no vertical motion. 

The figures below show a typical trapezon with source and destination pixrects, 
and some examples of filled regions that were drawn by pr_traprop ( ) . 

Figure D-l Typical Trapezon 



destination source 

pixrect pixrect 
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Figure D-2 Some Figures Drawn by pr_t raprop ( ) 




pr_traprop (dpr, dx, dy, t, op, spr, sx, sy) 

struct pixrect *dpr, *spr; 

struct pr_trap t; 

int dx, dy, sx, sy op; 

dpr and spr are pointers to the destination and source pixrects, respectively, t 
is the trapezon to be used, dx and dy specify an offset into the destination pix- 
rect. sx and sy specify an offset into the source pixrect. op is an op-code as 
specified previously (see Section 3.3, The Op Argument). 




pr_t raprop ( ) performs a rasterop from the source to the destination, clipped 
to the trapezon’s boundaries. A program must call pr_t raprop () once per 
trapezon; therefore this procedure must be called at least twice to draw the letter 
A in Figure D-2. 

The source pixrect is aligned with the destination pixrect; the pixel at (sx, sy) in 
the source pixrect goes to the pixel at (dx, dy) in the destination pixrect (see 
Figure D-2). 

Positions within the trapezon are relative to position (dx, dy) in the destination 
pixrect. Thus, a position defined as (0,0) in the trapezon would actually be at 
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(dx, dy) in the destination pixrect. 

The structure pr_trap defines the boundaries of a trapezon. A trapezon con- 
sists of pointers to two falls (left and right) and two y coordinates specify- 
ing the top and bottom of the trapezon (yO and yl). Note that the trapezon’s top 
and bottom may be of zero width; yO and yl may simply serve as points of 
reference. 

Each fall consists of a starting position (pos) and a pointer to the head of the list 
of chains describing the path the fall is to take (chain). A fall may start any- 
where above the trapezon and end anywhere below it. pr_traprop() ignores 
the portions of a fall that he above and below the trapezon. If a fall is shorter 
than the trapezon, pr_traprop ( ) will clip the trapezon horizontally to the 
endpoint of the fall in question. Figure D-3 illustrates the way this works. 

A chain is a member of a linked fist of structures that describes the movement 
of the fall. Each chain describes a single segment of the fall. Each chain consists 
of a pointer to the next member of the chain (next), the size of the bounding 
box for the chain (size), and a pointer to a bit vector containing motion com- 
mands (bits). 

Each chain may specify motion to the right and/or down, or motion to the left 
and/or down; however, a single chain may not specify both rightward and left- 
ward motion. Remember that motion may not proceed upward, and that straight 
horizontal motion is permitted. 

The x value of the chain’s size determines the direction of the motion: a posi- 
tive x value indicates rightward motion, while a negative x value indicates left- 
ward motion. The y value of the chain’s size must always be positive, since a 
fall may not move upward (in the direction of negative y). 

A chain’s bit vector is a command string that tells pr_traprop ( ) how to draw 
each segment of the fall. Each set (1) bit in the vector is a command to move one 
pixel horizontally and each clear (0) bit is a command to move one pixel verti- 
cally. The bits within the bit vector are stored in byte order, from most 
significant bit to least significant bit. This ordering corresponds to the left-to- 
right ordering of pixels within a memory pixrect. 

The fall begins at the starting position specified in pr_f all. The motion 
proceeds downward as specified in the first bit vector in the chain, from the 
high-order bit to the low-order bit. When the fall reaches the bottom of the 
bounding box, it continues at the top of the next chain’s bounding box. Note that 
the fall will always begin and end at diagonally opposite comers of a given 
bounding box. 

If a bit vector specifies a segment of the fall that would run outside of the bound- 
ing box, pr_traprop ( ) clips that segment of the fall to the bounding box. 
This would occur when the sum of the l’s in a chain’s bit vector exceeds the 
chain’s x size, or when the sum of the 0’s in the chain’s bit vector exceeds the 
chain’s y size. When this happens, the segment in question runs along the edge 
of the bounding box until it reaches the comer of the bounding box diagonally 
opposite to the comer in which it started. 
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Special Characters 
Crasterf ile . h>, 59 
<stdio .h>, 59 

8 

80386, see Sun386i 

B 

bitmap, 4 

bitmapped display, 4 
boolean, 4 

c 

clip pixrect, 21 

compiling pixrect programs, 6 

compute bounding box of text string, 46, 92 

compute location of characters in text string, 46, 92 

compute width and height of text string, 46, 92 

convert 680X0 pixrect to Sun386i pixrect, 91 

coordinate system, 4 

create memory pixrect, 53, 95 

create memory pixrect from an image, 53, 95 

create pixrect, 22, 91 

create secondary pixrect, 23, 91 

create static memory pixrect, 54, 95 

curved shapes, 109 

D 

determine supported plane groups, 37 

draw multiple points, 34 

draw textured or solid lines with width, 31, 98 

draw textured or solid polylines with width, 33 

draw textured polygon, 28, 98 

draw vector, 28, 98 

E 

exchange foreground and background colors, 35, 96 

F 

f bint r (),82 
f bmmap ( ) , 83 
f bopen ( ) , 83 
font 

pixrect, 28, 43, 45, 46 
fontedit, 44 



G 

get colormap entries, 34, 96 

get current plane group, 37 

get double buffering attributes, 38, 100 

get memory pixrect data bytes per line, 52, 95 

get pixel value, 24, 98 

get plane mask, 36, 96 

get pointer to memory pixrect data, 52, 95 

H 

header files 

pixrect, 6, 7 

i 

include files 

pixrect, 6, 7 

initialize raster file header, 65, 94 

L 

lint 

pixrect, 7 
load font, 44, 92 
load private copy of font, 45, 92 
load system default font, 45, 92 

M 

masked RasteiOp, 25, 98 
mem_create ( ) , 53, 95 
mem_jpoint () , 53, 95 
memory pixrects, 6, 13, 51, 53 
mpr_d ( ) , 52, 95 
mpr_data, 51 
mpr_linebytes () , 52, 95 
mpr_static ( ) , 54, 95 
multiple RasterOp, 27, 98 

o 

object-oriented programming, 5 

p 

pf_close ( ) , 45, 92 
pf_de fault ( ) , 45, 92 
pf_open ( ) , 44, 92 
pf_open_private ( ) , 45, 92 
pf_text () , 45, 92 
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pf_textbatch ( ) , 46, 92 
pf__t extbound ( ) , 46, 92 
pf_t ext width ( ) , 46, 92 
pf_ttext () , 45, 92 
PIX_CLR, 20 
PIX_DONTCLIP, 19, 21 
PIX_DST, 20 
P I X_ERR, 19 
PIXJNOT, 20 
PIXJSET, 20 
PIX_SRC, 20 
pixchar, 43, 103 
pixel, 51 

address, 4, 51, 55 
color, 4 

depth, 4, 51, 55 
Pixf ont, 43, 103 
Pixrect, 103 
pixrect 

available plane groups, 37 
bit flipping, 13 
bitmap, 4 
bitplane, 36 
clipping, 21, 86 
close a font, 45 
compiling, 6 
coordinate system, 4 
creation of, 22 

data structures, 7, 13, 18, 32, 43, 51, 63, 71, 73, 74, 75, 78, 84, 
103, 110 

destruction of, 24 
draw lines in, 31 
draw textured polygon in, 28 
draw vector in, 28 
errors, 19 

find character positions, 46 

font, 28, 43, 45, 46 

foreground and background, 35 

get colormap, 34 

get current plane group, 37 

get double buffering, 38 

get pixel of, 24 

get plane mask, 36 

header files, 6, 7 

internals, 18, 43, 51, 63 

lint library, 7 

load a font, 44 

load a private font, 45 

load default font, 45 

masked RasterOp, 25 

memory pixrects, 6, 13, 51, 53, 54 

multiple RasterOp, 27 

object, 5 

pixel, 4 

polylines, 33 

polypoints, 34 

portability, 13 

primary, 5 

raster files, 60, 62, 64, 65, 66 
RasterOp, 4, 25 
replicating, 26 
screen parameters, 22 



pixrect, continued 
secondary, 6, 23 
set colormap, 35 
set double buffering, 39 
set pixel, 24 
set plane group, 38 
set plane mask, 36 
string width, 46 
text bounding box, 46 
trapezon, 109 
write text, 45, 46 

writing device drivers, 69, 74, 76, 83, 86 
pixrect lint library, 7 
pixrect header files 

<pixrect /pixrect .h>, 6 
<pixrect/pr_planegroups .h>, 37 
<pixrect>, 7 
<stdio .h>, 59 
pixrect macros 

MP_D ISP LAY, 51 
MP_I386, 51 
MP_RE VERSEVI DEO, 51 
MP_STATIC, 51 
mpr_d ( ) , 52 
mpr_linebytes (), 52 
PIXJDONTCLIP, 19, 21 
PIX_DST, 20 
PIX_ERR, 19 
PIX_NOT, 20 
PIX_SRC, 20 
P I XP G_8 B I T_CO LOR, 37 
PIXPG_CURRENT, 37 
P I XP G_MON O, 37 
PIXPG_OVERLAY, 37 
PIXPG_OVERLAY_ENABLE, 37 
pixrectops, 18, 103 
pr__available_plane_groups () , 37 
pr__batchrop () , 27, 98 
pr_Jblackonwhite ( ) , 35, 96 
pr_brush, 103 
pr_brush ( ) , 31, 33 
pr_chain, 103, 110 
pr_clip () , 86 
pr__close ( ) , 24, 91 
pr_dbl_get (),38, 100 
pr_dbl_set ( ) , 39, 100 
pr_dest roy ( ) , 24, 91 
pr_dump ( ) , 60, 94 
pr_dump_header ( ) , 64, 94 
p r_du mp_i mage () , 65, 94 
p r_dump_i nit ( ) , 65, 94 
pr__fall, 103, 110 
pr_f lip (), 13,91 
pr_get (),24, 98 
pr__get_jplane__group () , 37 
pr_get attributes () , 36, 96 
pr_get colormap ( ) , 34, 96 
pr_line () , 31, 98 
pr_load ( ) , 62, 94 
pr_load_colormap () , 66, 94 
pr_load_header () , 65, 94 
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pr_load__image ( > , 66, 94 
pr_load_std_image () , 66, 94 
pr_makef romf d ( ) , 74 
pr_open ( ) , 22, 91 
pr_jpolygon_2 ( ) , 28, 98 
pr_jpolyline (), 33 
pr_j?olypoint () , 34 
pr_pos, 103 
pr_jprpos, 103 
pr_put (>,24, 98 
pr_putattributes () , 36, 96 
pr__put colormap () , 35, 96 
pr_region ( > , 23, 91 
pr_replrop () , 26, 98 
pr_reversedst () , 86 
pr^reversesrc () , 86 
pr_reversevideo ( ) , 35, 96 
pr_rop ( ) , 25, 98 
pr_set_plane_group () , 38 
pr_set_planes () , 38 
pr_size, 103 
pr_stencil () , 25, 98 
pr_subregion, 103 
pr_text ( ) , 46, 92 
Pr_texture, 103 
pr_texture () , 31, 33 
pr_trap, 103, 110 
pr_traprop () , 98, 109 
pr_ttext () , 46, 92 
pr_unmakef romf d ( ) , 76 
pr_vector ( ) , 28, 98 
pr_whiteonblack () , 35, 96 
primary pixrect, 5, 23 

prs_batchrop () , see pr_batchrop 
prs__destroy () , see pr_destroy 
prs__get ( ) , see pr_get 

prs_getattributes () , see pr_getattributes 
prs_getcolormap(), see pr_getcolormap 
pr s_put ( ) , see pr^put 

prs__putattributes () , see pr_put at tributes 
prs_put colormap O , see pr_j)utcolormap 
prs_region () , see pr__region 
prs_replrop ( ) , see pr_replrop 
prs_rop ( ) , see pr__rop 
prs_stencil ( ) , see pr_stencil 
prs_vector () , see pr_vector 



RasteiOp, 4, 25, 98 
read colormap from raster file, 66, 94 
read header from raster file, 65, 94 
read image from raster file, 66, 94 
read raster file, 62, 94 
read standard raster file, 66, 94 
release pixfont resources, 45, 92 
release pixrect resources, 24, 91 
replicated source RasterOp, 26, 98 
run-length encoding, 59 

s 

secondary pixrect, 6, 23 

set background and foreground colors, 35, 96 

set colormap entries, 35, 96 

set double buffering, 39, 100 

set foreground and background colors, 35, 96 

set pixel value, 24, 98 

set plane group and mask, 38 

set plane mask, 36, 96 

subregion 

creation of secondary pixrect, 23, 91 
destruction of pixrect, 24, 91 
draw vector in pixrect, 28, 98 
get colormap, 34, 96 
get pixel of pixrect, 24, 98 
get plane mask, 36, 96 
masked RasteiOp, 25, 98 
multiple RasterOp, 27, 98 
RasteiOp, 25, 98 
replicating, 26, 98 
set colormap, 35, 96 
set pixel of pixrect, 24, 98 
set plane mask, 36, 96 
Sun386i 

pixrect, 91 

pixrect portability, 13 
pr_flip(), 13 

T 

trapezon RasterOp, 98, 109 

u 

unstructured text, 46, 92 

v 

vector display, 4 
vertical retrace, 38 



R 

raster file 

data structure, 63 
initialize header, 65, 94 
read, 62, 66, 94 
read colormap, 66, 94 
read header, 65, 94 
read image, 66, 94 
write, 60, 94 
write header, 64, 94 
write image, 65, 94 
rasterf ile, 63 



w 

write header to raster file, 64, 94 

write image data to raster file, 65, 94 

write raster file, 60, 94 

write text, 45, 92 

write text and background, 45, 92 
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